diff --git a/docs/assert/expect.md b/docs/assert/expect.md
index 6819584ed..a6fbd02c9 100644
--- a/docs/assert/expect.md
+++ b/docs/assert/expect.md
@@ -1,7 +1,7 @@
---
layout: page-api
title: assert.expect()
-excerpt: Specify how many assertions are expected to run within a test.
+excerpt: Specify how many assertions are expected in a test.
groups:
- assert
redirect_from:
@@ -11,20 +11,61 @@ version_added: "1.0.0"
`expect( amount )`
-Specify how many assertions are expected to run within a test.
+Specify how many assertions are expected in a test.
| name | description |
|------|-------------|
-| `amount` | Number of assertions in this test. |
+| `amount` | Number of expected assertions in this test. |
-To ensure that an explicit number of assertions are run within any test, use `assert.expect()` to register an expected count. If the number of assertions run does not match the expected count, the test will fail.
+This is most commonly used as `assert.expect(0)`, which indicates that a test may pass making any assertions. This means the test is only used to verify that the code to completion without any uncaught errors. This is is essentially the inverse of [`assert.throws()`](./throws.md).
+
+It can also be used to explicitly require a certain number of assertions to be recorded in a given test. If afterwards the number of assertions does not match the expected count, the test will fail.
+
+It is recommended to test asynchronous code with [`assert.step()`](./step.md) or [`assert.async()`](./async.md) instead.
## Examples
-Establish an expected assertion count
+### Example: No assertions
+
+A test without any assertions:
+
+```js
+QUnit.test('example', function (assert) {
+ assert.expect(0);
+
+ var android = new Robot();
+ android.up(2);
+ android.down(2);
+ android.left();
+ android.right();
+ android.left();
+ android.right();
+ android.attack();
+ android.jump();
+});
+```
+
+### Example: Custom assert
+
+If you use a generic assertion library that throws when an expectation is not met, you can use `assert.expect(0)` if there are no other assertions needed in the test.
+
+```js
+QUnit.test('example', function (assert) {
+ assert.expect(0);
+
+ var android = new Robot(database);
+ android.run();
+
+ database.assertNoOpenConnections();
+});
+```
+
+### Example: Explicit count
+
+Require an explicit assertion count.
```js
-QUnit.test('a test', function (assert) {
+QUnit.test('example', function (assert) {
assert.expect(2);
function calc (x, operation) {
diff --git a/docs/callbacks/QUnit.begin.md b/docs/callbacks/QUnit.begin.md
index 70a556420..2b8cc9c91 100644
--- a/docs/callbacks/QUnit.begin.md
+++ b/docs/callbacks/QUnit.begin.md
@@ -1,7 +1,7 @@
---
layout: page-api
title: QUnit.begin()
-excerpt: Register a callback to fire whenever the test suite begins.
+excerpt: Register a callback to fire when the test run begins.
groups:
- callbacks
redirect_from:
@@ -11,21 +11,25 @@ version_added: "1.0.0"
`QUnit.begin( callback )`
-Register a callback to fire whenever the test suite begins. The callback may be an async function, or a function that returns a promise, which will be waited for before the next callback is handled.
+Register a callback to fire when the test run begins. The callback may be an async function, or a function that returns a Promise, which will be waited for before the next callback is handled.
The callback will be called once, before QUnit runs any tests.
| parameter | description |
|-----------|-------------|
-| callback (function) | Callback to execute. Provides a single argument with the callback Details object |
+| `callback` (function) | Callback to execute, called with a `details` object. |
### Details object
-Passed to the callback:
-
| property | description |
|-----------|-------------|
-| `totalTests` | The number of total tests in the test suite |
+| `totalTests` (number) | Number of registered tests |
+| `modules` (array) | List of registered modules,
as `{ name: string }` objects. |
+
+## Changelog
+
+| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | Added `details.modules` property, containing `{ name: string }` objects.
+| [QUnit 1.15](https://github.com/qunitjs/qunit/releases/tag/1.15.0) | Added `details.totalTests` property.
## Examples
diff --git a/docs/callbacks/QUnit.done.md b/docs/callbacks/QUnit.done.md
index 1281706e2..550ee9f75 100644
--- a/docs/callbacks/QUnit.done.md
+++ b/docs/callbacks/QUnit.done.md
@@ -1,7 +1,7 @@
---
layout: page-api
title: QUnit.done()
-excerpt: Register a callback to fire whenever the test suite ends.
+excerpt: Register a callback to fire when the test run has ended.
groups:
- callbacks
redirect_from:
@@ -11,37 +11,42 @@ version_added: "1.0.0"
`QUnit.done( callback )`
-Register a callback to fire whenever the test suite ends. The callback may be an async function, or a function that return a promise which will be waited for before the next callback is handled.
+Register a callback to fire when the test run has ended. The callback may be an async function, or a function that return a Promise which will be waited for before the next callback is handled.
| parameter | description |
|-----------|-------------|
-| callback (function) | Callback to execute. Provides a single argument with the callback Details object |
+| `callback` (function) | Callback to execute, called with a `details` object:
### Details object
-Passed to the callback:
-
| property | description |
|-----------|-------------|
-| `failed` (number) | The number of failed assertions |
-| `passed` (number) | The number of passed assertions |
-| `total` (number) | The total number of assertions |
-| `runtime` (number) | The time in milliseconds it took tests to run from start to finish. |
+| `failed` (number) | Number of failed assertions |
+| `passed` (number) | Number of passed assertions |
+| `total` (number) | Total number of assertions |
+| `runtime` (number) | Duration of the test run in milliseconds |
-## Examples
+
This method is __deprecated__ and it's recommended to use [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) instead.
+ | name | description | |------|-------------| | `target` | An object whose properties are to be modified | | `mixin` | An object describing which properties should be modified | -This method is __deprecated__ and it's recommended to use [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) instead.
- This method will modify the `target` object to contain the "own" properties defined by the `mixin`. If the `mixin` object specifies the value of any attribute as `undefined`, this property will instead be removed from the `target` object. ## Examples diff --git a/docs/extension/QUnit.push.md b/docs/extension/QUnit.push.md index 517a6e80b..8e28f16d5 100644 --- a/docs/extension/QUnit.push.md +++ b/docs/extension/QUnit.push.md @@ -3,8 +3,8 @@ layout: page-api title: QUnit.push() excerpt: Report the result of a custom assertion. groups: -- extension -- deprecated + - extension + - deprecated redirect_from: - "/config/QUnit.push/" version_added: "1.0.0" @@ -15,6 +15,8 @@ version_deprecated: "2.1.0" Report the result of a custom assertion. +This method is __deprecated__ and it's recommended to use [`pushResult`](../assert/pushResult.md) in the assertion context instead.
+ | name | description | |------|-------------| | `result` (boolean) | Result of the assertion | @@ -22,8 +24,6 @@ Report the result of a custom assertion. | `expected` | Known comparison value | | `message` (string) | A short description of the assertion | -This method is __deprecated__ and it's recommended to use [`pushResult`](../assert/pushResult.md) in the assertion context instead.
- `QUnit.push` reflects to the current running test, and it may leak assertions in asynchronous mode. Checkout [`assert.pushResult()`](../assert/pushResult.md) to set a proper custom assertion. Invoking `QUnit.push` allows to create a readable expectation that is not defined by any of QUnit's built-in assertions. diff --git a/docs/extension/QUnit.stack.md b/docs/extension/QUnit.stack.md index 972527003..9c0e10986 100644 --- a/docs/extension/QUnit.stack.md +++ b/docs/extension/QUnit.stack.md @@ -3,7 +3,7 @@ layout: page-api title: QUnit.stack() excerpt: Return a single line string representing the stacktrace. groups: -- extension + - extension redirect_from: - "/config/QUnit.stack/" version_added: "1.19.0" diff --git a/src/assert.js b/src/assert.js index 2bc73c06e..8685a9a94 100644 --- a/src/assert.js +++ b/src/assert.js @@ -58,8 +58,6 @@ class Assert { this.test.steps.length = 0; } - // Specify the number of expected assertions to guarantee that failed test - // (no assertions are run at all) don't slip through. expect (asserts) { if (arguments.length === 1) { this.test.expected = asserts; diff --git a/src/core.js b/src/core.js index aed626e66..35336c789 100644 --- a/src/core.js +++ b/src/core.js @@ -179,6 +179,10 @@ export function begin () { for (let i = 0; i < l; i++) { modulesLog.push({ name: config.modules[i].name, + + // Added in QUnit 1.16.0 for internal use by html-reporter, + // but no longer used since QUnit 2.7.0. + // @deprecated Kept unofficially to be removed in QUnit 3.0. tests: config.modules[i].tests }); } diff --git a/src/core/processing-queue.js b/src/core/processing-queue.js index bf23da93d..4e15ba16c 100644 --- a/src/core/processing-queue.js +++ b/src/core/processing-queue.js @@ -190,6 +190,9 @@ function done () { emit('runEnd', runSuite.end(true)); runLoggingCallbacks('done', { + // @deprecated since 2.19.0 Use done() without `details` parameter, + // or use `QUnit.on('runEnd')` instead. Parameter to be replaced in + // QUnit 3.0 with test counts. passed, failed: config.stats.bad, total: config.stats.all,