Docs: Misc tweaks on Step API, config.testTimeout and Intro.

Author: Krinkle

docs/api/assert/expect.md

@@ -38,10 +38,10 @@ Before, on QUnit 2.x without [QUnit.config.countStepsAsOne](../config/countSteps
 QUnit.test('example', async function (assert) {
   assert.expect(6);
 
-  MyWordParser.on('noun', function (word) {
+  MyVoice.on('noun', function (word) {
     assert.step(word); // 1, 2, 3, 4
   });
-  var song = await MyWordParser.sing('My Favorite Things', { lines: 1 });
+  var song = await MyVoice.sing('My Favorite Things', { lines: 1 });
 
   assert.true(song.finished, 'finished'); // 5
   assert.verifySteps([ // 6
@@ -59,10 +59,10 @@ After:
 QUnit.test('example', async function (assert) {
   assert.expect(2);
 
-  MyWordParser.on('noun', function (word) {
+  MyVoice.on('noun', function (word) {
     assert.step(word);
   });
-  var song = await MyWordParser.sing('My Favorite Things', { lines: 1 });
+  var song = await MyVoice.sing('My Favorite Things', { lines: 1 });
 
   assert.true(song.finished, 'finished'); // 1
   assert.verifySteps([ // 2

docs/api/assert/step.md

@@ -29,20 +29,23 @@ The Step API provides an easy way to verify execution logic to a high degree of
 
 ```js
 QUnit.test('example', function (assert) {
-  var maker = new WordMaker();
-  maker.on('start', () => {
+  const finder = new WordFinder();
+  finder.on('start', () => {
     assert.step('start');
   });
-  maker.on('data', (word) => {
+  finder.on('data', (word) => {
     assert.step(word);
   });
-  maker.on('end', () => {
+  finder.on('end', () => {
     assert.step('end');
   });
+  finder.on('error', message => {
+    assert.step('error: ' + message);
+  });
 
-  maker.process('3.1');
+  finder.process('Hello, 3.1. Great!');
 
-  assert.verifySteps([ 'start', '3', 'point', '1', 'end' ]);
+  assert.verifySteps(['start', 'Hello', 'Great', 'end']);
 });
 ```
 

docs/api/assert/verifySteps.md

@@ -22,11 +22,11 @@ The Step API provides an easy way to verify execution logic to a high degree of
 
 For example, you can mark steps to observe and validate whether parts of your code are reached correctly, or to check the frequency (how often) an asynchronous code path is executed. You can also capture any unexpected steps, which are automatically detected and shown as part of the test failure.
 
-This assertion compares a given array of string values to a list of previously recorded steps, as marked via previous calls to [`assert.step()`](./step.md).
+This assertion compares a given array of string values to a list of steps recorded via calls to [`assert.step()`](./step.md).
 
-Calling `verifySteps()` will clear and reset the internal list of steps. This allows multiple independent sequences of `assert.step()` to exist within the same test.
+Calling `assert.verifySteps()` will clear and reset the internal list of steps. This allows multiple independent sequences of `assert.step()` to exist within the same test.
 
-Refer to the below examples and learn how to use the Step API in your test suite.
+Refer to the below examples to learn how to use the Step API in your test suite.
 
 ## Changelog
 
@@ -36,14 +36,14 @@ Refer to the below examples and learn how to use the Step API in your test suite
 
 ### Test event-based interface
 
-This example uses a class based on an [`EventEmitter`](https://nodejs.org/api/events.html), such as the one provided by Node.js and other environments:
+These two examples test classes that emits event via an `on()` method. It might be based on an [`EventEmitter`](https://nodejs.org/api/events.html), such as the one found in Node.js and in other environments:
 
 ```js
 QUnit.test('good example', async function (assert) {
-  MyWordParser.on('noun', function (word) {
+  MyVoice.on('noun', function (word) {
     assert.step(word);
   });
-  const song = await MyWordParser.sing('My Favorite Things', { lines: 1 });
+  const song = await MyVoice.sing('My Favorite Things', { lines: 1 });
 
   assert.true(song.finished, 'finished');
   assert.verifySteps([
@@ -57,23 +57,23 @@ QUnit.test('good example', async function (assert) {
 
 ```js
 QUnit.test('good example', async function (assert) {
-  const maker = new WordMaker();
-  maker.on('start', () => {
+  const finder = new WordFinder();
+  finder.on('start', () => {
     assert.step('start');
   });
-  maker.on('data', (word) => {
+  finder.on('data', (word) => {
     assert.step(word);
   });
-  maker.on('end', () => {
+  finder.on('end', () => {
     assert.step('end');
   });
-  maker.on('error', message => {
+  finder.on('error', message => {
     assert.step('error: ' + message);
   });
 
-  await maker.process('3.1');
+  await finder.process('Hello, 3.1. Great!');
 
-  assert.verifySteps(['start', '3', 'point', '1', 'end']);
+  assert.verifySteps(['start', 'Hello', 'Great', 'end']);
 });
 ```
 
@@ -82,17 +82,17 @@ If you approach this scenario *without* the Step API, one might be tempted to pl
 ```js
 // WARNING: This is a BAD example
 QUnit.test('bad example 1', async function (assert) {
-  const maker = new WordMaker();
-  maker.on('start', () => {
+  const finder = new WordFinder();
+  finder.on('start', () => {
     assert.true(true, 'start');
   });
-  maker.on('middle', () => {
+  finder.on('middle', () => {
     assert.true(true, 'middle');
   });
-  maker.on('end', () => {
+  finder.on('end', () => {
     assert.true(true, 'end');
   });
-  maker.on('error', () => {
+  finder.on('error', () => {
     assert.true(false, 'error');
   });
 
@@ -106,21 +106,21 @@ A less fragile approach could involve a local array that we check afterwards wit
 QUnit.test('manual example without Step API', async function (assert) {
   const values = [];
 
-  const maker = new WordMaker();
-  maker.on('start', () => {
+  const finder = new WordFinder();
+  finder.on('start', () => {
     values.push('start');
   });
-  maker.on('middle', () => {
+  finder.on('middle', () => {
     values.push('middle');
   });
-  maker.on('end', () => {
+  finder.on('end', () => {
     values.push('end');
   });
-  maker.on('error', () => {
+  finder.on('error', () => {
     values.push('error');
   });
 
-  await maker.process();
+  await finder.process();
 
   assert.deepEqual(values, ['start', 'middle', 'end']);
 });

docs/api/config/testTimeout.md

@@ -28,15 +28,9 @@ Individual tests can override the default `testTimeout` config via [assert.timeo
 
 It is recommended to set the default at `3000` or higher (3 seconds). A lower timeout may cause intermittent failures due to unrelated infrastructure delays that are known to sometimes occur inside CI services and other virtual servers.
 
-## Introducing a default timeout
-
-Prior to QUnit 3, there has not been a default timeout. This meant that a test hang silently for many seconds or minutes before diagnostic details are presented (e.g. after a CI job reaches the maximum run time).
-
-QUnit 3.0 will change the default timeout from undefined (Infinity) to 3 seconds.
-
-### Deprecated: No timeout set
+## Deprecated: No timeout set
 
-Starting in QUnit 2.21, a deprecation warning will be logged if a test takes longer than 3 seconds, when there is no timeout set.
+Starting in QUnit 2.21, a deprecation warning is logged if a test takes longer than 3 seconds, and there is no timeout set.
 
 ```
 Test {name} took longer than 3000ms, but no timeout was set.
@@ -63,7 +57,7 @@ You can address this warning before upgrading to QUnit 3 as follows:
 
 * Or, your test runner of choice may offer other ways to set configuration.
 
-  For example, to set `testTimeout` via [karma-qunit](https://github.com/karma-runner/karma-qunit/#readme):
+  For example, set `testTimeout` via [karma-qunit](https://github.com/karma-runner/karma-qunit/#readme):
 
   ```js
   config.set({
@@ -77,6 +71,12 @@ You can address this warning before upgrading to QUnit 3 as follows:
   });
   ```
 
+## Introducing a default timeout
+
+Prior to QUnit 3.0, there has not been a default timeout. This meant that a test could hang silently for many seconds or minutes before diagnostic details are presented (e.g. after a CI job reaches the maximum run time).
+
+QUnit 3.0 changes the default timeout from undefined (Infinity) to 3 seconds.
+
 ## Changelog
 
 | [QUnit 2.21.0](https://github.com/qunitjs/qunit/releases/tag/2.21.0) | Announce change of default from undefined to `3000`, with a deprecation warning.

docs/api/reporters/console.md

@@ -40,13 +40,13 @@ runEnd {…}
 qunit --reporter console test/
 ```
 
-Enable manually in JavaScript code (since QUnit 2.16):
+Enable manually in JavaScript code:
 
 ```js
 QUnit.reporters.console.init(QUnit);
 ```
 
-Enable declaratively via [QUnit.config](../config/index.md) (since QUnit 3.0):
+Enable declaratively via [QUnit.config](../config/index.md):
 
 ```js
 // Preconfig:

docs/intro.md

@@ -20,13 +20,14 @@ redirect_from:
 Check these QUnit tutorials and examples, to make the most of your unit tests!
 
 1. [QUnit.module](./api/QUnit/module.md#organizing-your-tests): How to group related tests.
-1. [QUnit.test](./api/QUnit/test.md#examples): Define tests, How to wait for async code
+1. [QUnit.test](./api/QUnit/test.md#examples): Define tests, How to wait for async code.
 1. [Fixture feature](./browser.md#fixture): Keeping your DOM tests atomic.
 1. [Step API](./api/assert/verifySteps.md): Testing asynchronous callbacks or event listeners.
 1. [Assertions](./api/assert/index.md): Partial object comparison, expected exceptions, and much more.
 1. [Browser](./browser.md): Productivity tricks, Browser automation, What can the toolbar do?
 1. [CLI](./cli.md): Productivity tricks, Code coverage.
 1. [Reporter API](./callbacks/QUnit.on.md#reporter-api): Event emitter, Create your own reporter.
+1. [Theme API](./browser.md#theme-api): Create your own theme.
 
 ## Support