Document Node.js requirements and test details

Fixes #191.

CONTRIBUTING.md

@@ -33,12 +33,19 @@ To be more specific, before submitting your pull request please ensure:
 * Your change is backward-compatible (or you've explicitly said that it's not; this isn't great, but will be considered).
 * You haven't changed any files in `dist/` (these are auto-generated, and should only be changed on release).
 
+Compatibility and JavaScript Runtimes
+-------------------------------------
+
+loglevel aims to stay compatible with browsers, Node.js versions, and other JS runtimes that may be fairly old at this point! Please take care to match existing conventions and JavaScript language features wherever possible. For example, loglevel uses `var` instead of the newer `let` and `const` keywords to define variables, uses old-style `for` loops instead of the newer `for...of` loop, and so on.
+
+That said, loglevel's *test and development tools* utilize newer JavaScript and Node.js features. To run most tests or build releases, you will need a newer version of Node.js than is required at runtime (see details below in ["how to make your change…"](#how-to-make-your-change-and-submit-it)). Using newer features or making breaking changes to the *dev tools* is OK.
+
 Project structure
 -----------------
 
 The core project code is all in [`lib/loglevel.js`](./lib/loglevel.js), and this should be the only file you need to touch for functional changes themselves.
 
-The released code is in `dist/*.js`, and should not be touched by anything except releases.
+The released code is in `dist/*.js`, and should not be touched by anything except releases (pull requests should *not* update these files).
 
 The test suite is entirely in `test/*.js`:
 
@@ -50,14 +57,40 @@ The test suite is entirely in `test/*.js`:
 How to make your change and submit it
 -------------------------------------
 
-1. Fork loglevel.
-2. Clone your fork locally.
-3. Create a branch from `master` for your change.
-4. Write some tests in `test/` for your change, as relevant.
-5. Make your code changes in `lib/loglevel.js`.
-6. Check your code all passes (run `grunt`) - if you have any issues try running `grunt jasmine:requirejs:src:build` (or a different test build instead of `requirejs`: see the Jasmine config in `Gruntfile.js`) and debugging the generated _SpecRunner.html in a browser.
-7. Commit your changes.
-8. Open a pull request back to `master` in loglevel.
+1. Ensure you have Node.js v14 or later (some tests can run on earlier versions, but the full suite requires this version).
+2. Fork loglevel.
+3. Clone your fork locally.
+4. Create a branch from `master` for your change.
+5. Write some tests in `test/` for your change, as relevant.
+6. Make your code changes in `lib/loglevel.js`.
+7. Check your code all passes (run `npm test`). If you have issues and need to debug the tests, see the details on ["running tests"](#running-tests) below.
+8. Commit your changes.
+9. Open a pull request back to `master` in loglevel.
+
+Running Tests
+-------------
+
+There are several types of tests and test tools that loglevel uses to verify different types of support in different environments. When you run `npm test`, *all* of these tests are run automatically. However, you may want to run individual types of tests during development, or run some tests manually to debug them.
+
+Test commands (see `"scripts"` in `package.json` for a complete list of tools):
+- `npm test` — Runs all the below tests.
+- `npm run test-browser` — Runs detailed tests in a headless browser. There are actually 3 sub-groups here:
+    - `npx grunt jasmine:global` — Tests general usage of the global `log` variable.
+    - `npx grunt test-browser-context` — Tests usage when loglevel is injected into an anonymous function instead of included as a regular script on the page.
+    - `npx grunt jasmine:requirejs` — Tests the main test suite via Jasmine & RequireJS.
+- `npm run test-node` — Runs tests that check loglevel in Node.js.
+- `npm run test-types` — Runs tests of the TypeScript type definitions for loglevel.
+
+Alternatively, you might want to run tests manually in your browser in order to use debugging tools to step through the code:
+1. Run `npx grunt integration-test` to start a test server on port `8000`.
+2. Your default browser should open the tests automatically, but if not, open `http://127.0.0.1:8000/_SpecRunner.html` in any browser.
+3. Open your browser's dev tools and place breakpoints where you'd like to debug a test.
+4. Reload the page to re-run the tests and pause on breakpoints.
+
+You can also open a blank webpage with loglevel pre-loaded to experiment in your browser's console:
+1. Run `npx grunt integration-test` to start a test server on port `8000`.
+2. In whatever browser you want to test, open `http://127.0.0.1:8000/test/manual-test.html`.
+3. Play around with the global `log` object in the browser's dev console.
 
 Reporting security issues
 -------------------------

Gruntfile.js

@@ -153,7 +153,8 @@ module.exports = function (grunt) {
 
     // Check everything is good
     grunt.registerTask('test', ['jshint', 'test-browser', 'test-node']);
-    grunt.registerTask('test-browser', ['jasmine:global', 'preprocess', 'jasmine:context', 'clean:test', 'jasmine:requirejs']);
+    grunt.registerTask('test-browser', ['jasmine:global', 'test-browser-context', 'jasmine:requirejs']);
+    grunt.registerTask('test-browser-context', ['preprocess', 'jasmine:context', 'clean:test']);
     grunt.registerTask('test-node', ['jasmine_node']);
 
     // Test with a live server and an actual browser