268 QUnit/module.md
View file
@@ -0,0 +1,268 @@
---
layout: default
title: module
description: Group related tests under a single label.
categories:
- main
---

## `QUnit.module( name [, hooks] [, nested ] )`

Group related tests under a single label.

| parameter | description |
|-----------|-------------|
| `name` (string) | Label for this group of tests. |
| `hooks` (object) | Callbacks to run during test execution. |
| `nested` (function) | A callback used for nested modules. |

#### hooks properties: `{ before, beforeEach, afterEach, after }`

| name | description |
|-----------|-------------|
| `before` (function) | Runs before the first test. |
| `beforeEach` (function) | Runs before each test. |
| `afterEach` (function) | Runs after each test. |
| `after` (function) | Runs after the last test. |

> Note: If additional tests are defined after the module's queue has emptied, it will not run the `after` hook again.
#### Nested module: `nested( hooks )`

A callback with grouped tests and nested modules to run under the current module label.

| name | description |
|-----------|-------------|
| `hooks` (object) | Runs before the first test. |

### Description

You can use the module name to organize, select, and filter tests to run.

All tests inside a module callback function will be grouped into that module. The test names will all be preceded by the module name in the test results. Other modules can be nested inside this callback function, where their tests' names will be labeled by their names recursively prefixed by their parent modules.

If `QUnit.module` is defined without a `nested` callback argument, all subsequently defined tests will be grouped into the module until another module is defined.

Modules with test group functions allow you to define nested modules, and QUnit will run tests on the parent module before going deep on the nested ones, even if they're declared first. Additionally, any hook callbacks on a parent module will wrap the hooks on a nested module. In other words, `before` and `beforeEach` callbacks will form a [queue][] while the `afterEach` and `after` callbacks will form a [stack][].

[queue]: https://en.wikipedia.org/wiki/Queue_%28abstract_data_type%29
[stack]: https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29

You can specify code to run before and after tests using the hooks argument, and also to create properties that will be shared on the testing context. Any additional properties on the `hooks` object will be added to that context. The `hooks` argument is still optional if you call `QUnit.module` with a callback argument.

The module's callback is invoked with the test environment as its `this` context, with the environment's properties copied to the module's tests, hooks, and nested modules. Note that changes on tests' `this` are not preserved between sibling tests, where `this` will be reset to the initial value for each test.

`QUnit.module()`'s hooks can automatically handle the asynchronous resolution of a Promise on your behalf if you return a `then`able Promise as the result of your callback function.

### Examples

Use the `QUnit.module()` function to group tests together:

```js
QUnit.module( "group a" );
QUnit.test( "a basic test example", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.test( "a basic test example 2", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.module( "group b" );
QUnit.test( "a basic test example 3", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.test( "a basic test example 4", function( assert ) {
assert.ok( true, "this test is fine" );
});
```

Using modern syntax:

```js
const { test } = QUnit;
QUnit.module( "group a" );
test( "a basic test example", t => {
t.ok( true, "this test is fine" );
});
test( "a basic test example 2", t => {
t.ok( true, "this test is fine" );
});
QUnit.module( "group b" );
test( "a basic test example 3", t => {
t.ok( true, "this test is fine" );
});
test( "a basic test example 4", t => {
t.ok( true, "this test is fine" );
});
```

---

Use the `QUnit.module()` function to group tests together:

```js
QUnit.module( "module a", function() {
QUnit.test( "a basic test example", function( assert ) {
assert.ok( true, "this test is fine" );
});
});
QUnit.module( "module b", function() {
QUnit.test( "a basic test example 2", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.module( "nested module b.1", function() {
// This test will be prefixed with the following module label:
// "module b > nested module b.1"
QUnit.test( "a basic test example 3", function( assert ) {
assert.ok( true, "this test is fine" );
});
});
});
```

Using modern syntax:

```js
const { test } = QUnit;
QUnit.module( "module a", () => {
test( "a basic test example", t => {
t.ok( true, "this test is fine" );
});
});
QUnit.module( "module b", () => {
test( "a basic test example 2", t => {
t.ok( true, "this test is fine" );
});
QUnit.module( "nested module b.1", () => {
// This test will be prefixed with the following module label:
// "module b > nested module b.1"
test( "a basic test example 3", t => {
t.ok( true, "this test is fine" );
});
});
});
```

---

A sample for using the before, beforeEach, afterEach, and after callbacks

```js
QUnit.module( "module A", {
before: function() {
// prepare something once for all tests
},
beforeEach: function() {
// prepare something before each test
},
afterEach: function() {
// clean up after each test
},
after: function() {
// clean up once after all tests are done
}
});
```

---

Hooks share the same context as their respective test

```js
QUnit.module( "Machine Maker", {
beforeEach: function() {
this.maker = new Maker();
this.parts = [ "wheels", "motor", "chassis" ];
}
});
QUnit.test( "makes a robot", function( assert ) {
this.parts.push( "arduino" );
assert.equal( this.maker.build( this.parts ), "robot" );
assert.deepEqual( this.maker.made, [ "robot" ] );
});
QUnit.test( "makes a car", function( assert ) {
assert.equal( this.maker.build( this.parts ), "car" );
this.maker.duplicate();
assert.deepEqual( this.maker.made, [ "car", "car" ] );
});
```

---

Hooks stack on nested modules

```js
QUnit.module( "grouped tests argument hooks", function( hooks ) {
hooks.beforeEach( function( assert ) {
assert.ok( true, "beforeEach called" );
} );
hooks.afterEach( function( assert ) {
assert.ok( true, "afterEach called" );
} );
QUnit.test( "call hooks", function( assert ) {
assert.expect( 2 );
} );
QUnit.module( "stacked hooks", function( hooks ) {
// This will run after the parent module's beforeEach hook
hooks.beforeEach( function( assert ) {
assert.ok( true, "nested beforeEach called" );
} );
// This will run before the parent module's afterEach
hooks.afterEach( function( assert ) {
assert.ok( true, "nested afterEach called" );
} );
QUnit.test( "call hooks", function( assert ) {
assert.expect( 4 );
} );
} );
} );
```

---

An example of handling an asynchronous `then`able Promise result in hooks. This example uses an [ES6 Promise][] interface that is fulfilled after connecting to or disconnecting from database.

[ES6 Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

```js
QUnit.module( "Database connection", {
before: function() {
return new Promise( function( resolve, reject ) {
DB.connect( function( err ) {
if ( err ) {
reject( err );
} else {
resolve();
}
} );
} );
},
after: function() {
return new Promise( function( resolve, reject ) {
DB.disconnect( function( err ) {
if ( err ) {
reject( err );
} else {
resolve();
}
} );
} );
}
} );
```
80 QUnit/only.md
View file
@@ -0,0 +1,80 @@
---
layout: default
title: only
description: Adds a test to exclusively run, preventing all other tests from running.
categories:
- main
---

## `QUnit.only( name, callback )`

Adds a test to exclusively run, preventing all other tests from running.

| parameter | description |
|-----------|-------------|
| `name` (string) | Title of unit being tested |
| `callback` (function) | Function to close over assertions |

#### Callback parameters: `callback( assert )`:

| parameter | description |
|-----------|-------------|
| `assert` (object) | A new instance object with the [assertion methods](/api/assert) |

### Description

Use this method to focus your test suite on a specific test. `QUnit.only` will cause any other tests in your suite to be ignored.

Note that if more than one `QUnit.only` is present only the first instance will run.

This is an alternative to filtering tests to run in the HTML reporter. It is especially useful when you use a console reporter or in a codebase with a large set of long running tests.

### Example

How to use `QUnit.only` to filter your test suite.

```js
QUnit.module( "robot", {
beforeEach: function() {
this.robot = new Robot();
}
});
QUnit.test( "say", function( assert ) {
assert.ok( false, "I'm not quite ready yet" );
});
QUnit.test( "stomp", function( assert ) {
assert.ok( false, "I'm not quite ready yet" );
});
// You're currently working on the laser feature, so we run only this test
QUnit.only( "laser", function( assert ) {
assert.ok( this.robot.laser() );
});
```

Using modern syntax:

```js
const { test, only } = QUnit;
QUnit.module( "robot", {
beforeEach: function() {
this.robot = new Robot();
}
});
test( "say", t => {
t.ok( false, "I'm not quite ready yet" );
});
test( "stomp", t => {
t.ok( false, "I'm not quite ready yet" );
});
// You're currently working on the laser feature, so we run only this test
only( "laser", function( t ) {
t.ok( this.robot.laser() );
});
```
65 QUnit/skip.md
View file
@@ -0,0 +1,65 @@
---
layout: default
title: skip
description: Adds a test like object to be skipped
categories:
- main
---

## `QUnit.skip( name )`

Adds a test like object to be skipped

| parameter | description |
|-----------|-------------|
| `name` (string) | Title of unit being tested |

### Description

Use this method to replace [`QUnit.test()`](/QUnit/test/) instead of commenting out entire tests.

This test's prototype will be listed on the suite as a skipped test, ignoring the callback argument and the respective global and module's hooks.

### Example

How to use `skip` as a placeholder for future or temporarily broken tests.

```js
QUnit.module( "robot", {
beforeEach: function() {
this.robot = new Robot();
}
});
QUnit.test( "say", function( assert ) {
assert.strictEqual( this.robot.say(), "Exterminate!" );
});
// Robot doesn't have a laser method, yet, skip this test
// Will show up as skipped in the results
QUnit.skip( "laser", function( assert ) {
assert.ok( this.robot.laser() );
});
```

Using modern syntax:

```js
const { test, skip } = QUnit;
QUnit.module( "robot", {
beforeEach() {
this.robot = new Robot();
}
});
test( "say", function( t ) {
t.strictEqual( this.robot.say(), "Exterminate!" );
});
// Robot doesn't have a laser method, yet, skip this test
// Will show up as skipped in the results
skip( "laser", function( t ) {
t.ok( this.robot.laser() );
});
```
28 QUnit/start.md
View file
@@ -0,0 +1,28 @@
---
layout: default
title: start
description: QUnit.start() is used to start an async test set
categories:
- main
- async
---

## `QUnit.start()`

`QUnit.start()` must be used to start a test run that has [`QUnit.config.autostart`](/api/config/QUnit.config/) set to `false`.

<p class="warning">Warning: This method was previously used to control async tests on text contexts along with `QUnit.stop`. For asynchronous tests, use [`assert.async`](/api/assert/async/) instead.</p>

When your async test has multiple exit points, call `QUnit.start()` for the corresponding number of `QUnit.stop()` increments.

### Example

A test run that does not begin when the page is done loading. This example uses an Asynchronous Module Definition (AMD) loader-style `require` call.

```js
QUnit.config.autostart = false;
require(["test/tests1.js", "test/tests2.js"], function() {
QUnit.start();
});
```
109 QUnit/test.md
View file
@@ -0,0 +1,109 @@
---
layout: default
title: test
description: Add a test to run.
categories:
- main
- async
---

## `QUnit.test( name, callback )`

Add a test to run.

| parameter | description |
|-----------|-------------|
| `name` (string) | Title of unit being tested |
| `callback` (function) | Function to close over assertions |

#### Callback parameters: `callback( assert )`:

| parameter | description |
|-----------|-------------|
| `assert` (object) | A new instance object with the [assertion methods](/api/assert) |

### Description

Add a test to run using `QUnit.test()`.

The `assert` argument to the callback contains all of QUnit's [assertion methods](/api/assert). Use this argument to call your test assertions.

`QUnit.test()` can automatically handle the asynchronous resolution of a Promise on your behalf if you return a `then`able Promise as the result of your callback function.

### Examples

A practical example, using the assert argument and no globals.

```js
function square( x ) {
return x * x;
}
QUnit.test( "square()", function( assert ) {
var result = square( 2 );
assert.equal( result, 4, "square(2) equals 4" );
});
```

Using modern syntax:

```js
function square( x ) {
return x * x;
}
const { test } = QUnit;
test( "square()", t => {
t.equal( square( 2 ), 4, "square(2) equals 4" );
t.equal( square( 3 ), 9, "square(3) equals 9" );
});
```

---

An example of handling an asynchronous `then`able Promise result. This example uses an [ES6 Promise][] interface that is fulfilled after waiting 500ms.

[ES6 Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

```js
QUnit.test( "a Promise-returning test", function( assert ) {
assert.expect( 1 );
var thenable = new Promise(function( resolve, reject ) {
setTimeout(function() {
assert.ok( true );
resolve( "result" );
}, 500 );
});
return thenable;
});
```

---

Following the example above, `QUnit.test` also supports JS [async functions][] syntax out of the box.

[async functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function

```js
function squareAfter1Second(x) {
return new Promise(resolve => {
setTimeout(() => {
resolve(x * x);
}, 1000);
});
}
const { test } = QUnit;
test( "an async test", async t => {
var a = await squareAfter1Second(2);
var b = await squareAfter1Second(3);
t.equal( a, 4 );
t.equal( b, 9 );
t.equal( await squareAfter1Second(5), 25 );
});
```
46 QUnit/todo.md
View file
@@ -0,0 +1,46 @@
---
layout: default
title: todo
description: Adds a test which expects at least one failing assertion during its run.
categories:
- main
---

## `QUnit.todo( name, callback )`

Adds a test which expects at least one failing assertion during its run.

| parameter | description |
|-----------|-------------|
| `name` (string) | Title of unit being tested |
| `callback` (function) | Function to close over assertions |

#### Callback parameters: `callback( assert )`:

| parameter | description |
|-----------|-------------|
| `assert` (object) | A new instance object with the [assertion methods](/api/assert) |

### Description

Use this method to test a unit of code which is still under development (in a "todo" state). The test will pass as long as one failing assertion is present.

If all assertions pass, then the test will fail signaling that `QUnit.todo` should be replaced by `QUnit.test`.

### Example

How to use `QUnit.todo` to denote code that is still under development.

```js
QUnit.module( "robot", {
beforeEach: function() {
this.robot = new Robot();
}
});
// fireLazer hasn't been properly implemented yet, so this is a todo test
QUnit.todo( "fireLazer returns the correct value", function( assert ) {
var result = this.robot.fireLazer(); // Currently returns undefined
assert.equal( result, "I'm firing my lazer!" );
});
```
37 _config.yml
View file
@@ -0,0 +1,37 @@
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.

# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via {{ site.myvariable }}.
title: QUnit API Docs
# email: your-email@domain.com
description: > # this means to ignore newlines until "baseurl:"
API reference documentation for QUnit
baseurl: "/api" # the subpath of your site, e.g. /blog
url: "https://api.qunitjs.com" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: qunitjs
github_username: qunitjs

highlighter: rouge
markdown: kramdown
kramdown:
input: GFM

exclude:
- Gemfile
- Gemfile.lock
- README.md
- CONTRIBUTING.md
- CNAME

permalink: title
61 _layouts/default.html
View file
@@ -0,0 +1,61 @@
---
layout: wrapper
---

<section class="sidebar">
<h2>Main methods:</h2>
<ul class="sidebar-list">
{% assign methods = site.pages | where:'categories', 'main' %}
{% for page in methods %}
<li class="sidebar-item">
<a href="{{ page.url | prepend:site.baseurl }}">{{page.title}}</a>
</li>
{% endfor %}
</ul>

<h2>Assertions:</h2>
<ul class="sidebar-list">
{% assign assertions = site.pages | where:'categories', 'assert' %}
{% for page in assertions %}
<li class="sidebar-item">
<a href="{{ page.url | prepend:site.baseurl }}">{{page.title}}</a>
</li>
{% endfor %}
</ul>

<h2>Config:</h2>

<ul class="sidebar-list">
{% assign config = site.pages | where:'categories', 'config' %}
{% for page in config %}
<li class="sidebar-item">
<a href="{{ page.url | prepend:site.baseurl }}">{{page.title}}</a>
</li>
{% endfor %}
</ul>

<h2>Callbacks:</h2>

<ul class="sidebar-list">
{% assign callbacks = site.pages | where:'categories', 'callbacks' %}
{% for page in callbacks %}
<li class="sidebar-item">
<a href="{{ page.url | prepend:site.baseurl }}">{{page.title}}</a>
</li>
{% endfor %}
</ul>

<h2>Async control:</h2>

<ul class="sidebar-list">
{% assign async = site.pages | where:'categories', 'async' %}
{% for page in async %}
<li class="sidebar-item">
<a href="{{ page.url | prepend:site.baseurl }}">{{page.title}}</a>
</li>
{% endfor %}
</ul>
</section>
<div id="main" class="main" role="main">
{{ content }}
</div>
13 _layouts/home.html
View file
@@ -0,0 +1,13 @@
---
layout: default
title: Home
---

<p>QUnit is a powerful, easy-to-use JavaScript unit test suite.
If you're new to QUnit or even just new to unit testing, you might
want to check out the <a href="http://qunitjs.com/intro/">Introduction
to JavaScript Unit Testing</a>. There's also a
<a href="http://qunitjs.com/cookbook/">QUnit Cookbook</a> on the
<a href="http://qunitjs.com/">main site</a>.</p>

<p>QUnit has no dependencies and works in all browsers.</p>
19 _layouts/page.html
View file
@@ -0,0 +1,19 @@
---
layout: wrapper
---

<div id="main" class="main" role="main">
{{ content }}

<h2>{{ page.title }}:</h2>

<ul class="page-list">
{% assign pages = site.pages | where:'categories', page.category %}
{% for page in pages %}
<li class="page-item">
<h3><a href="{{ page.url | prepend:site.baseurl }}">{{page.title}}</a></h3>
<p>{{page.description}}</p>
</li>
{% endfor %}
</ul>
</div>
43 _layouts/wrapper.html
View file
@@ -0,0 +1,43 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ page.title }} | QUnit API Docs</title>
<link rel="icon" href="/favicon.ico">
<link rel="stylesheet" href="{{ site.baseurl }}/css/styles.css" media="screen">
<meta name="twitter:creator" content="@qunitjs">
<meta name="twitter:site" content="@qunitjs">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:description" content="API reference documentation for QUnit">
<meta name="twitter:title" content="QUnit API Docs">
</head>
<body class="{{ page.type }}">
<a class="a11y" href="#main">skip to content</a>
<div>
<header class="site-header" role="banner">
<div class="site-header-wrapper">
<div class="site-logo">
<h1 class="logo"><a class="logo-link" href="{{ site.baseurl }}/">QUnit API Docs</a></h1>
</div>
<nav role="navigation" class="site-nav">
<ul class="site-nav-list">
{% assign topics = site.pages | where:'categories', 'topics' %}
{% for topic in topics %}
<li class="site-nav-list-item">
<a class="site-nav-list-link" href="{{ topic.url | prepend:site.baseurl }}">
{{ topic.title }}
</a>
</li>
{% endfor %}
</ul>
</nav>
</div>
</header>
<div class="wrapper">
{{ content }}
</div>
</div>
</body>
</html>
80 assert/async.md
View file
@@ -0,0 +1,80 @@
---
layout: default
title: async
description: Instruct QUnit to wait for an asynchronous operation.
categories:
- assert
- async
---

## `async( [ acceptCallCount = 1 ] )`

Instruct QUnit to wait for an asynchronous operation.

| name | description |
|------|-------------|
| `acceptCallCount` (Number) | Number of expected callbacks before the test is done. Defaults to `1`. |

### Description

The callback returned from `assert.async()` will throw an Error if it is invoked more than once (or more often than the accepted call count, if provided).

This replaces functionality previously provided by [`QUnit.stop()`](/QUnit/stop) and [`QUnit.start()`](/QUnit/start).

### Examples

Tell QUnit to wait for the `done()` call inside the timeout.

```js
QUnit.test( "assert.async() test", function( assert ) {
var done = assert.async();
var input = $( "#test-input" ).focus();
setTimeout(function() {
assert.equal( document.activeElement, input[0], "Input was focused" );
done();
});
});
```

Call `assert.async()` for each operation. Each `done` callback can be called at most once.

```js
QUnit.test( "two async calls", function( assert ) {
assert.expect( 2 );
var done1 = assert.async();
var done2 = assert.async();
setTimeout(function() {
assert.ok( true, "test resumed from async operation 1" );
done1();
}, 500 );
setTimeout(function() {
assert.ok( true, "test resumed from async operation 2" );
done2();
}, 150);
});
```

Set up an async test three exit points. Each `done()` call adds up to the `acceptCallCount`. After three calls, the test is done.

```js
QUnit.test( "multiple call done()", function( assert ) {
assert.expect( 3 );
var done = assert.async( 3 );
setTimeout(function() {
assert.ok( true, "first call done." );
done();
}, 500 );
setTimeout(function() {
assert.ok( true, "second call done." );
done();
}, 500 );
setTimeout(function() {
assert.ok( true, "third call done." );
done();
}, 500 );
});
```
34 assert/deepEqual.md
View file
@@ -0,0 +1,34 @@
---
layout: default
title: deepEqual
description: A deep recursive comparison, working on primitive types, arrays, objects, regular expressions, dates and functions.
categories:
- assert
---

## `deepEqual( actual, expected [, message ] )`

A deep recursive comparison, working on primitive types, arrays, objects, regular expressions, dates and functions.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `deepEqual()` assertion can be used just like `equal()` when comparing the value of objects, such that `{ key: value }` is equal to `{ key: value }`. For non-scalar values, identity will be disregarded by `deepEqual`.

[`notDeepEqual()`](/api/assert/notDeepEqual/) can be used to explicitly test deep, strict inequality.

### Examples

Compare the value of two objects.
```js
QUnit.test( "deepEqual test", function( assert ) {
var obj = { foo: "bar" };
assert.deepEqual( obj, { foo: "bar" }, "Two objects can be the same in value" );
});
```
48 assert/equal.md
View file
@@ -0,0 +1,48 @@
---
layout: default
title: equal
description: A non-strict comparison.
categories:
- assert
---

## `equal( actual, expected [, message ] )`

A non-strict comparison, roughly equivalent to JUnit's `assertEquals`.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `equal` assertion uses the simple comparison operator (`==`) to compare the actual and expected arguments. When they are equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message.

[`notEqual()`](/api/assert/notEqual/) can be used to explicitly test inequality.

[`strictEqual()`](/api/assert/strictEqual/) can be used to test strict equality.

### Examples

The simplest assertion example:

```js
QUnit.test( "a test", function( assert ) {
assert.equal( 1, "1", "String '1' and number 1 have the same value" );
});
```

A slightly more thorough set of assertions:

```js
QUnit.test( "equal test", function( assert ) {
assert.equal( 0, 0, "Zero, Zero; equal succeeds" );
assert.equal( "", 0, "Empty, Zero; equal succeeds" );
assert.equal( "", "", "Empty, Empty; equal succeeds" );
assert.equal( "three", 3, "Three, 3; equal fails" );
assert.equal( null, false, "null, false; equal fails" );
});
```
40 assert/expect.md
View file
@@ -0,0 +1,40 @@
---
layout: default
title: expect
description: Specify how many assertions are expected to run within a test.
categories:
- assert
---

## `expect( amount )`

Specify how many assertions are expected to run within a test.

| name | description |
|------|-------------|
| `amount` | Number of assertions in this test. |

### Description

To ensure that an explicit number of assertions are run within any test, use `assert.expect( number )` to register an expected count. If the number of assertions run does not match the expected count, the test will fail.

### Examples

Establish an expected assertion count

```js
QUnit.test( "a test", function( assert ) {
assert.expect( 2 );
function calc( x, operation ) {
return operation( x );
}
var result = calc( 2, function( x ) {
assert.ok( true, "calc() calls operation function" );
return x * x;
});
assert.equal( result, 4, "2 squared equals 4" );
});
```
7 assert/index.md
View file
@@ -0,0 +1,7 @@
---
layout: page
title: Assertions
category: assert
categories:
- topics
---
35 assert/notDeepEqual.md
View file
@@ -0,0 +1,35 @@
---
layout: default
title: notDeepEqual
description: An inverted deep recursive comparison, working on primitive types, arrays, objects, regular expressions, dates and functions.
categories:
- assert
---

## `notDeepEqual( actual, expected [, message ] )`

An inverted deep recursive comparison, working on primitive types, arrays, objects, regular expressions, dates and functions.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `notDeepEqual()` assertion can be used just like `equal()` when comparing the value of objects, such that `{ key: value }` is equal to `{ key: value }`. For non-scalar values, identity will be disregarded by `notDeepEqual`.

[`deepEqual()`](/api/assert/deepEqual/) can be used to explicitly test deep, strict equality.

### Examples

Compare the value of two objects.

```js
QUnit.test( "notDeepEqual test", function( assert ) {
var obj = { foo: "bar" };
assert.notDeepEqual( obj, { foo: "bla" }, "Different object, same key, different value, not equal" );
});
```
35 assert/notEqual.md
View file
@@ -0,0 +1,35 @@
---
layout: default
title: notEqual
description: A non-strict comparison, checking for inequality.
categories:
- assert
---

## `notEqual( actual, expected [, message ] )`

A non-strict comparison, checking for inequality.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `notEqual` assertion uses the simple inverted comparison operator (`!=`) to compare the actual and expected arguments. When they aren't equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message.

[`equal()`](/api/assert/equal) can be used to test equality.

[`notStrictEqual()`](/api/assert/notStrictEqual) can be used to test strict inequality.

### Examples

The simplest assertion example:

```js
QUnit.test( "a test", function( assert ) {
assert.notEqual( 1, "2", "String '2' and number 1 don't have the same value" );
});
```
36 assert/notOk.md
View file
@@ -0,0 +1,36 @@
---
layout: default
title: notOk
description: A boolean check. Passes if the first argument is falsy.
categories:
- assert
---

## `notOk( state [, message ] )`

A boolean check, inverse of `ok()` and CommonJS's `assert.ok()`, and equivalent to JUnit's `assertFalse()`. Passes if the first argument is falsy.

| name | description |
|--------------------|--------------------------------------|
| state | Expression being tested |
| message (string) | A short description of the assertion |

### Description

`notOk()` requires just one argument. If the argument evaluates to false, the assertion passes; otherwise, it fails. If a second message argument is provided, it will be displayed in place of the result.

### Examples:

```js
QUnit.test( "notOk test", function( assert ) {
assert.notOk( false, "false succeeds" );
assert.notOk( "", "empty string succeeds" );
assert.notOk( NaN, "NaN succeeds" );
assert.notOk( null, "null succeeds" );
assert.notOk( undefined, "undefined succeeds" );
assert.notOk( true, "true fails" );
assert.notOk( 1, "1 fails" );
assert.notOk( "not-empty", "not-empty string fails" );
});
```
46 assert/notPropEqual.md
View file
@@ -0,0 +1,46 @@
---
layout: default
title: notPropEqual
description: A strict comparison of an object's own properties, checking for inequality.
categories:
- assert
---

## `notPropEqual( actual, expected [, message ] )`

A strict comparison of an object's own properties, checking for inequality.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

The `notPropEqual` assertion uses the strict inverted comparison operator (`!==`) to compare the actual and expected arguments as Objects regarding only their properties but not their constructors.

When they aren't equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message.

[`equal()`](/api/assert/equal/) can be used to test equality.

[`propEqual()`](/api/assert/propEqual/) can be used to test strict equality of an Object properties.

### Examples

Compare the values of two objects properties.

```js
QUnit.test( "notPropEqual test", function( assert ) {
function Foo( x, y, z ) {
this.x = x;
this.y = y;
this.z = z;
}
Foo.prototype.doA = function () {};
Foo.prototype.doB = function () {};
Foo.prototype.bar = 'prototype';
var foo = new Foo( 1, "2", [] );
var bar = new Foo( "1", 2, {} );
assert.notPropEqual( foo, bar, "Properties values are strictly compared." );
});
```
35 assert/notStrictEqual.md
View file
@@ -0,0 +1,35 @@
---
layout: default
title: notStrictEqual
description: A strict comparison, checking for inequality.
categories:
- assert
---

## `notStrictEqual( actual, expected [, message ] )`

A strict comparison, checking for inequality.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `notStrictEqual` assertion uses the strict inverted comparison operator (`!==`) to compare the actual and expected arguments. When they aren't equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message.

[`equal()`](/api/assert/equal/) can be used to test equality.

[`strictEqual()`](/api/assert/strictEqual/) can be used to test strict equality.

### Examples

The simplest assertion example:

```js
QUnit.test( "a test", function( assert ) {
assert.notStrictEqual( 1, "1", "String '1' and number 1 have the same value but not the same type" );
});
```
34 assert/ok.md
View file
@@ -0,0 +1,34 @@
---
layout: default
title: ok
description: A boolean check, equivalent to CommonJS's assert.ok() and JUnit's assertTrue(). Passes if the first argument is truthy.
categories:
- assert
---

## `ok( state [, message ] )`

A boolean check, equivalent to CommonJS's assert.ok() and JUnit's assertTrue(). Passes if the first argument is truthy.

| name | description |
|--------------------|--------------------------------------|
| `state` | Expression being tested |
| `message` (string) | A short description of the assertion |

### Description

The most basic assertion in QUnit, `ok()` requires just one argument. If the argument evaluates to true, the assertion passes; otherwise, it fails. If a second message argument is provided, it will be displayed in place of the result.

```js
QUnit.test( "ok test", function( assert ) {
assert.ok( true, "true succeeds" );
assert.ok( "non-empty", "non-empty string succeeds" );
assert.ok( false, "false fails" );
assert.ok( 0, "0 fails" );
assert.ok( NaN, "NaN fails" );
assert.ok( "", "empty string fails" );
assert.ok( null, "null fails" );
assert.ok( undefined, "undefined fails" );
});
```
50 assert/propEqual.md
View file
@@ -0,0 +1,50 @@
---
layout: default
title: propEqual
description: A strict type and value comparison of an object's own properties.
categories:
- assert
---

## `propEqual( actual, expected [, message ] )`

A strict type and value comparison of an object's own properties.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `propEqual()` assertion provides strictly (`===`) comparison of Object properties. Unlike `deepEqual()`, this assertion can be used to compare two objects made with different constructors and prototype.

[`strictEqual()`](/api/assert/strictEqual/) can be used to test strict equality.

[`notPropEqual()`](/api/assert/notPropEqual/) can be used to explicitly test strict inequality of Object properties.

### Example

Compare the properties values of two objects.

```js
QUnit.test( "propEqual test", function( assert ) {
function Foo( x, y, z ) {
this.x = x;
this.y = y;
this.z = z;
}
Foo.prototype.doA = function () {};
Foo.prototype.doB = function () {};
Foo.prototype.bar = 'prototype';
var foo = new Foo( 1, "2", [] );
var bar = {
x : 1,
y : "2",
z : []
};
assert.propEqual( foo, bar, "Strictly the same properties without comparing objects constructors." );
});
```
45 assert/pushResult.md
View file
@@ -0,0 +1,45 @@
---
layout: default
title: pushResult
description: Report the result of a custom assertion.
categories:
- assert
---

## `pushResult( data: { result, actual, expected, message } )`

Report the result of a custom assertion.

| name | description |
|--------------------|--------------------------------------|
| `data.result` (boolean) | Result of the assertion |
| `data.actual` | Expression being tested |
| `data.expected` | Known comparison value |
| `data.message` (string) | A short description of the assertion |

Some test suites may need to express an expectation that is not defined by any of QUnit's built-in assertions. This need may be met by encapsulating the expectation in a JavaScript function which returns a `Boolean` value representing the result; this value can then be passed into QUnit's `ok` assertion.

A more readable solution would involve defining a custom assertion. If the expectation function invokes `pushResult`, QUnit will be notified of the result and report it accordingly.

### Example

Define a custom `mod2` assertion that tests if the provided numbers are equivalent in modulo 2.

```js
QUnit.assert.mod2 = function( value, expected, message ) {
var actual = value % 2;
this.pushResult( {
result: actual === expected,
actual: actual,
expected: expected,
message: message
} );
};
QUnit.test( "mod2", function( assert ) {
assert.expect( 2 );
assert.mod2( 2, 0, "2 % 2 == 0" );
assert.mod2( 3, 1, "3 % 2 == 1" );
});
```
31 assert/step.md
View file
@@ -0,0 +1,31 @@
---
layout: default
title: step
description: A marker for progress in a given test.
categories:
- assert
---

## `step( [ message ] )`

A marker for progress in a given test.

| name | description |
|--------------------|--------------------------------------|
| `message` (string) | Message to display for the step |

### Description

The `step()` assertion registers a passing assertion with a provided message. This makes it easy to check that specific portions of code are being executed, especially in asynchronous test cases and when used with `verifySteps()`. A step will always pass unless a message is not provided.

### Example

```js
QUnit.test( "step test", function( assert ) {
assert.expect( 1 );
obj.hook = function() {
assert.step('Hook is called!');
};
obj.invokeHookIndirectly();
});
```
35 assert/strictEqual.md
View file
@@ -0,0 +1,35 @@
---
layout: default
title: strictEqual
description: A strict type and value comparison.
categories:
- assert
---

## `strictEqual( actual, expected [, message ] )`

A strict type and value comparison.

| name | description |
|--------------------|--------------------------------------|
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

### Description

The `strictEqual()` assertion provides the most rigid comparison of type and value with the strict equality operator (`===`).

[`equal()`](/api/assert/equal/) can be used to test non-strict equality.

[`notStrictEqual()`](/api/assert/notStrictEqual/) can be used to explicitly test strict inequality.

### Example

Compare the value of two primitives, having the same value and type.

```js
QUnit.test( "strictEqual test", function( assert ) {
assert.strictEqual( 1, 1, "1 and 1 have the same value and type" );
});
```
84 assert/throws.md
View file
@@ -0,0 +1,84 @@
---
layout: default
title: throws
description: Test if a callback throws an exception, and optionally compare the thrown error.
categories:
- assert
---

## `throws( blockFn, expected [, message ] )`

Test if a callback throws an exception, and optionally compare the thrown error.

| name | description |
|--------------------|--------------------------------------|
| `blockFn` (function) | Function to execute |
| `expected` | Expected Error |
| `message` (string) | A short description of the assertion |


### Description

When testing code that is expected to throw an exception based on a specific set of circumstances, use `assert.throws()` to catch the error object for testing and comparison.

The `expected` argument can be an Error Object (instance), an Error Function (constructor), a RegExp that matches (or partially matches) the String representation, or a callback Function that must return `true` to pass the assertion check.

> In very few environments, like Closure Compiler, `throws` is considered a reserved word and will cause an error. For that case, an alias is bundled called `raises`. It has the same signature and behaviour, just a different name.
### Example

Assert the correct error message is received for a custom error object.

```js
QUnit.test( "throws", function( assert ) {
function CustomError( message ) {
this.message = message;
}
CustomError.prototype.toString = function() {
return this.message;
};
assert.throws(
function() {
throw "error"
},
"throws with just a message, not using the 'expected' argument"
);
assert.throws(
function() {
throw new CustomError("some error description");
},
/description/,
"raised error message contains 'description'"
);
assert.throws(
function() {
throw new CustomError();
},
CustomError,
"raised error is an instance of CustomError"
);
assert.throws(
function() {
throw new CustomError("some error description");
},
new CustomError("some error description"),
"raised error instance matches the CustomError instance"
);
assert.throws(
function() {
throw new CustomError("some error description");
},
function( err ) {
return err.toString() === "some error description";
},
"raised error instance satisfies the callback function"
);
});
```
40 assert/verifySteps.md
View file
@@ -0,0 +1,40 @@
---
layout: default
title: verifySteps
description: A helper assertion to verify the order and number of steps in a test.
categories:
- assert
---

## `verifySteps( steps [, message ] )`

A helper assertion to verify the order and number of steps in a test.

| name | description |
|--------------------|--------------------------------------|
| `steps` (array) | Array of strings representing steps to verify |
| `message` (string) | A short description of the assertion |

### Description

The `verifySteps()` assertion compares a given array of string values (representing steps) and compares them with the order and values of previous `step()` calls. This assertion is helpful for verifying the order of execution for asynchronous flows.

### Examples

```js
QUnit.test( "step test", function( assert ) {
obj.start = function() {
assert.step('start');
};
obj.middle = function() {
assert.step('middle');
};
obj.end = function() {
assert.step('end');
};
return obj.process().then(function() {
assert.verifySteps(['start', 'middle', 'end']);
});
});
```
7 async.md
View file
@@ -0,0 +1,7 @@
---
layout: page
title: Async Control
category: async
categories:
- topics
---
41 callbacks/QUnit.begin.md
View file
@@ -0,0 +1,41 @@
---
layout: default
title: QUnit.begin
description: Register a callback to fire whenever the test suite begins.
categories:
- callbacks
---

## `QUnit.begin( callback )`

Register a callback to fire whenever the test suite begins.

`QUnit.begin()` is called once before running any tests.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { totalTests } )`

| parameter | description |
|-----------|-------------|
| `totalTests` | The number of total tests in the test suite |

### Example

Get total amount of tests.

```js
QUnit.begin(function( details ) {
console.log( "Test amount:", details.totalTests );
});
```

Using modern syntax:

```js
QUnit.begin( ( { totalTests } ) => {
console.log( `Test amount: ${totalTests}` );
});
```
42 callbacks/QUnit.done.md
View file
@@ -0,0 +1,42 @@
---
layout: default
title: QUnit.done
description: Register a callback to fire whenever the test suite ends.
categories:
- callbacks
---

## `QUnit.done( callback )`

Register a callback to fire whenever the test suite ends.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { failed, passed, total, runtime } )`

| parameter | 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. |

### Example

Register a callback that logs test results to the console.

```js
QUnit.done(function( details ) {
console.log( "Total: ", details.total, " Failed: ", details.failed, " Passed: ", details.passed, " Runtime: ", details.runtime );
});
```

Using modern syntax:

```js
QUnit.done( ( { total, failed, passed, runtime } ) => {
console.log( `Total: ${total}, Failed: ${failed}, Passed: ${passed}, Runtime: ${runtime}` );
});
```
95 callbacks/QUnit.log.md
View file
@@ -0,0 +1,95 @@
---
layout: default
title: QUnit.log
description: Register a callback to fire whenever an assertion completes.
categories:
- callbacks
---

## `QUnit.log( callback )`

Register a callback to fire whenever an assertion completes.

This is one of several callbacks QUnit provides. Its intended for integration scenarios like PhantomJS or Jenkins.
The properties of the details argument are listed below as options.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { result, actual, expected, message, source, module, name, runtime } )`

| parameter | description |
|-----------|-------------|
| `result` (boolean) | The boolean result of an assertion, `true` means passed, `false` means failed. |
| `actual` | One side of a comparision assertion. Can be _undefined_ when `ok()` is used. |
| `expected` | One side of a comparision assertion. Can be _undefined_ when `ok()` is used. |
| `message` (string) | A string description provided by the assertion. |
| `source` (string) | The associated stacktrace, either from an exception or pointing to the source of the assertion. Depends on browser support for providing stacktraces, so can be undefined. |
| `module` (string) | The test module name of the assertion. If the assertion is not connected to any module, the property's value will be _undefined_. |
| `name` (string) | The test block name of the assertion. |
| `runtime` (number) | The time elapsed in milliseconds since the start of the containing [`QUnit.test()`](/QUnit/test/), including setup. |

### Examples

Register a callback that logs the assertion result and its message

```js
QUnit.log(function( details ) {
console.log( "Log: ", details.result, details.message );
});
```

Using modern syntax:

```js
QUnit.log( ( { result, message } ) => {
console.log( `Log: ${result}, ${message}` );
});
```

---

Logs the module and test block whenever an assertion fails.

```js
QUnit.log(function( details ) {
if ( details.result ) {
return;
}
var loc = details.module + ": " + details.name + ": ",
output = "FAILED: " + loc + ( details.message ? details.message + ", " : "" );
if ( details.actual ) {
output += "expected: " + details.expected + ", actual: " + details.actual;
}
if ( details.source ) {
output += ", " + details.source;
}
console.log( output );
});
```

Using modern syntax:

```js
QUnit.log( ( { result, module, name, message, actual, expected, source } ) => {
if ( result ) {
return;
}
let output = `FAILED: ${module}: ${name}: `;
if ( message ) {
output += `${message}, `;
}
if ( actual ) {
output += `expected: ${expected}, actual: ${actual}`;
}
if ( source ) {
output += `, ${source}`;
}
console.log( output );
});
```
43 callbacks/QUnit.moduleDone.md
View file
@@ -0,0 +1,43 @@
---
layout: default
title: QUnit.moduleDone
description: Register a callback to fire whenever a module ends.
categories:
- callbacks
---

## `QUnit.moduleDone( callback )`

Register a callback to fire whenever a module ends.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { name, failed, passed, total, runtime } )`

| parameter | description |
|-----------|-------------|
| `name` (string) | Name of this module |
| `failed` (number) | The number of failed assertions |
| `passed` (number) | The number of passed assertions |
| `total` (number) | The total number of assertions |
| `runtime` (number) | The execution time in millseconds of this module |

### Example

Register a callback that logs the module results

```js
QUnit.moduleDone(function( details ) {
console.log( "Finished running: ", details.name, "Failed/total: ", details.failed, details.total );
});
```

Using modern syntax:

```js
QUnit.moduleDone( ( { name, failed, total } ) => {
console.log( `Finished running: ${name} Failed/total: ${failed}, ${total}` );
});
```
39 callbacks/QUnit.moduleStart.md
View file
@@ -0,0 +1,39 @@
---
layout: default
title: QUnit.moduleStart
description: Register a callback to fire whenever a module begins.
categories:
- callbacks
---

## `QUnit.moduleStart( callback )`

Register a callback to fire whenever a module begins.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { name } )`

| parameter | description |
|-----------|-------------|
| `name` (string) | Name of the next module to run |

### Example

Register a callback that logs the module name

```js
QUnit.moduleStart(function( details ) {
console.log( "Now running: ", details.name );
});
```

Using modern syntax:

```js
QUnit.moduleStart( ( { name } ) => {
console.log( `Now running: ${name}` );
});
```
44 callbacks/QUnit.on.md
View file
@@ -0,0 +1,44 @@
---
layout: default
title: QUnit.on
description: Register a callback to fire whenever the specified event is emitted.
categories:
- callbacks
---

## `QUnit.on( eventName, callback )`

Register a callback to fire whenever the specified event is emitted. Conforms to the [js-reporters standard](https://github.com/js-reporters/js-reporters).

`QUnit.on()` allows you to listen for events related to the test suite's execution. Available event names and corresponding data payloads are defined in the [js-reporters specification](https://github.com/js-reporters/js-reporters).

| parameter | description |
|-----------|-------------|
| eventName (string) | The name of the event for which to execute the provided callback. |
| callback (function) | Callback to execute. Receives a single argument representing the data for the event. |

### Example

Printing results of a test suite.

```js
QUnit.on( "runEnd", function( data ) {
console.log( "Passed: " + data.testCounts.passed );
console.log( "Failed: " + data.testCounts.failed );
console.log( "Skipped: " + data.testCounts.skipped );
console.log( "Todo: " + data.testCounts.todo );
console.log( "Total: " + data.testCounts.total );
} );
```

Using modern syntax:

```js
QUnit.on( "runEnd", ( { testCounts: { passed, failed, skipped, todo, total } } ) => {
console.log( `Passed: ${passed}` );
console.log( `Failed: ${failed}` );
console.log( `Skipped: ${skipped}` );
console.log( `Todo: ${todo}` );
console.log( `Total: ${total}` );
} );
```
69 callbacks/QUnit.testDone.md
View file
@@ -0,0 +1,69 @@
---
layout: default
title: QUnit.testDone
description: Register a callback to fire whenever a test ends.
categories:
- callbacks
---

## `QUnit.testDone( callback )`

Register a callback to fire whenever a test ends.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { name, module, failed, passed, total, runtime, skipped } )`

| parameter | description |
|-----------|-------------|
| `name` (string) | Name of the current test |
| `module` (string) | Name of the current module |
| `failed` (number) | The number of failed assertions |
| `passed` (number) | The number of passed assertions |
| `total` (number) | The total number of assertions |
| `runtime` (number) | The execution time in millseconds of the test, including beforeEach and afterEach calls |
| `skipped` (boolean) | Indicates whether or not the current test was skipped |

### Example

Register a callback that logs results of a single test

```js
QUnit.testDone( function( details ) {
var result = {
"Module name": details.module,
"Test name": details.name,
"Assertions": {
"Total": details.total,
"Passed": details.passed,
"Failed": details.failed
},
"Skipped": details.skipped,
"Runtime": details.runtime
};
console.log( JSON.stringify( result, null, 2 ) );
} );
```

Using modern syntax:

```js
QUnit.testDone( ( { module, name, total, passed, failed, skipped, runtime } ) => {
var result = {
"Module name": module,
"Test name": name,
"Assertions": {
"Total": total,
"Passed": passed,
"Failed": failed
},
"Skipped": skipped,
"Runtime": runtime
};
console.log( JSON.stringify( result, null, 2 ) );
} );
```
42 callbacks/QUnit.testStart.md
View file
@@ -0,0 +1,42 @@
---
layout: default
title: QUnit.testStart
description: Register a callback to fire whenever a test begins.
categories:
- callbacks
---

## `QUnit.testStart( callback )`

Register a callback to fire whenever a test begins.

| parameter | description |
|-----------|-------------|
| callback (function) | Callback to execute. Provides a single argument with the callback details object |

#### Callback details: `callback( details: { name, module, testId, previousFailure } )`

| parameter | description |
|-----------|-------------|
| `name` (string) | Name of the next test to run |
| `module` (string) | Name of the current module |
| `testId` (string) | Id of the next test to run |
| `previousFailure` (boolean) | Whether the next test failed on a previous run |

### Example

Register a callback that logs the module and name

```js
QUnit.testStart(function( details ) {
console.log( "Now running: ", details.module, details.name );
});
```

Using modern syntax:

```js
QUnit.testStart( ( { module, name } ) => {
console.log( `Now running: ${module}: ${name}` );
});
```
7 callbacks/index.md
View file
@@ -0,0 +1,7 @@
---
layout: page
title: Callback handlers
category: callbacks
categories:
- topics
---
19 categories.xml
View file

This file was deleted.

5 config-sample.json
View file

This file was deleted.

25 config/QUnit.assert.md
View file
@@ -0,0 +1,25 @@
---
layout: default
title: QUnit.assert
description: Namespace for QUnit assertions.
categories:
- config
---

## `QUnit.assert`

Namespace for QUnit assertions.

QUnit's built-in assertions are defined on the `QUnit.assert` object. An instance of this object is passed as the only argument to the `QUnit.test` function callback.

This object has properties for each of [QUnit's built-in assertion methods](/api/assert/).

### Example

Use the `ok` assertion through the test callback parameter:

```js
QUnit.test( "`ok` assertion defined in the callback parameter", function( assert ) {
assert.ok( true, "on the object passed to the `test` function" );
});
```
191 config/QUnit.config.md
View file
@@ -0,0 +1,191 @@
---
layout: default
categories: [config]
title: QUnit.config
description: General configuration for QUnit. Check the description of each option for details.
---

## `QUnit.config`

Configuration for QUnit. QUnit has a bunch of internal configuration defaults, some of which are useful to override. Check the description for each option for details.

### `QUnit.config.altertitle` (boolean) | default: `true`

By default, QUnit updates document.title to add a checkmark or x-mark to indicate if a testsuite passed or failed. This makes it easy to see a suites result even without looking at a tab's content.

If you're dealing with code that tests `document.title` changes or have some other problem with this feature, set this option to false to disable it.

### `QUnit.config.autostart` (boolean) | default: `true`

By default, QUnit runs tests when `load` event is triggered on the `window`. If you're loading tests asynchronously, you can set this property to `false`, then call `QUnit.start()` once everything is loaded. See below for an example.

### `QUnit.config.collapse` (boolean) | default: `true`

By default, QUnit's HTML reporter collapses consecutive failing tests showing only the details for the first failed test. The other tests can be expanded manually with a single click on the test title. Setting this value to `false` will expand the details for every failing test.

### `QUnit.config.current` (object)

This object isn't actually a configuration property, but is listed here anyway, as it's exported through `QUnit.config`. This gives you access to some QUnit internals at runtime. See below for an example.

### `QUnit.config.filter` (string) | default: `undefined`

Allows you to filter which tests are run by matching the module name and test title against the provided string. You can do an inverse filter, matching all tests that don't contain the string, by prefixing a `!` to the value.

You can also match via a regular expression by passing in a string version of the regular expression literal, such as `/(this|that)/i`.

### `QUnit.config.fixture` (string) | default: `undefined`

Defines the HTML content to use in the fixture container which is reset at the start of each test.

By default QUnit will use whatever the starting content of `#qunit-fixture` is as the fixture reset. If you do not want the fixture to be reset in between tests, set the value to `null`.

### `QUnit.config.hidepassed` (boolean) | default: `false`

By default, the HTML Reporter will show all the tests results. Enabling this option will make it show only the failing tests, hiding all that pass. This can also be managed by the HTML interface.

### `QUnit.config.maxDepth` (number) | default: `5`

Specifies the depth up-to which an object will be dumped during a diff. To run without a max depth, use a value of `-1`.

### `QUnit.config.module` (string) | default: `undefined`

Specify a single module to run by name (exact case-insensitive match required). By default, QUnit will run all the loaded modules when this property is not specified.

This property was absent in versions 1.16.0 through 1.22.0.

### `QUnit.config.moduleId` (array) | default: `undefined`

This property allows QUnit to run specific modules identified by the hashed version of their module name. You can specify one or multiple modules to run.

### `QUnit.config.notrycatch` (boolean) | default: `false`

By default, QUnit will run tests within a `try-catch` block to prevent uncaught exceptions from crashing the entire test suite.

Enabling this flag will run tests without the `try-catch` to allow exceptions to remain uncaught for easier debugging in certain environments.

### `QUnit.config.noglobals` (boolean) | default: `false`

Enabling this flag will cause QUnit to check if any new properties have been added to the global context after each test. New global properties being found will result in test failures to help ensure your tests are not leaking state.

### `QUnit.config.seed` (string) | default: `undefined`

This property tells QUnit to run tests in a seeded-random order. The value provided will be used as the seed in a pseudo-random number generator to ensure that results are reproducible. The randomization will also respect the `reorder` option if enabled and re-run failed tests first without randomizing them.

Randomly ordering your tests can help identify non-atomic tests which either depend on a previous test or are leaking state to following tests. This is particularly beneficial in a development CI or post-commit process.

If `seed` is specified in the page's url parameters, but no value is specified, then QUnit will generate a random value to use as the seed. You can access the value from this property and use it to repeat the same sequence in another run.

### `QUnit.config.storage` (object) | default: `sessionStorage`

Defines the storage object used to record failed tests between runs. The object must implement [the `Storage` interface][Storage] of the Web Storage API.

[Storage]: https://html.spec.whatwg.org/multipage/webstorage.html#the-storage-interface

Defaults to the global `sessionStorage` if defined.

### `QUnit.config.reorder` (boolean) | default: `true`

By default, QUnit will run tests first that failed on a previous run. In a large testsuite, this can speed up testing a lot.

It can also lead to random errors, in case your testsuite has non-atomic tests, where the order is important. You should fix those issues, instead of disabling reordering!

When a failed test is running first, `Rerunning previously failed test` is displayed in the summary whereas just `Running` is displayed otherwise.

### `QUnit.config.requireExpects` (boolean) | default: `false`

The `expect()` method is optional by default, though it can be useful to require each test to specify the number of expected assertions.

Enabling this option will cause tests to fail, if they don't call `expect()` at all.

### `QUnit.config.testId` (array) | default: `undefined`

This property allows QUnit to run specific tests identified by the hashed version of their module name and test name. You can specify one or multiple tests to run.

### `QUnit.config.testTimeout` (number) | default: `undefined`

Specify a global timeout in milliseconds after which all tests will fail with an appropriate message. Useful when async tests aren't finishing, to prevent the testrunner getting stuck. Set to something high, e.g. 30000 (30 seconds) to avoid slow tests to time out by accident.

### `QUnit.config.scrolltop` (boolean) | default: `true`

By default, scroll to top of the page when suite is done. Setting this to false will leave the page scroll alone.

### `QUnit.config.urlConfig` (array)

This property controls which form controls to put into the QUnit toolbar element (below the header). By default, the "noglobals" and "notrycatch" checkboxes are there. By extending this array, you can add your own checkboxes and select lists.

Each element should be an object with an `id` property (used as the config and query-string key) and a `label` property (used as text in the UI), and optionally a `tooltip` property (used as the title attribute to explain what the control does). Each element should also have a `value` property controlling available options and rendering.

If `value` is undefined, the option will render as a checkbox. The corresponding URL parameter will be set to "true" when the checkbox is checked, and otherwise will be absent.

If `value` is a string, the option will render as a checkbox. The corresponding URL parameter will be set to the string when the checkbox is checked, and otherwise will be absent.

If `value` is an array, the option will render as a select-one with an empty first option, followed by an option for each element of the array, with text and value matching the element. The corresponding URL parameter will be absent when the empty option is selected, and otherwise will be set to the value of the selected array element.

If `value` is an object, the option will render as a select-one with an empty first option, followed by an option for each property of the object, with text and value matching the name and value (respectively) of the property. The corresponding URL parameter will be absent when the empty option is selected, and otherwise will be set to the value of the selected object property.

See also the examples below.

### Examples

Disable autostart, useful when loading tests asynchronsly, here using requirejs:

```js
QUnit.config.autostart = false;
require(
[ "tests/testModule1", "tests/testModule2" ],
function() {
QUnit.start();
}
);
```

Access `QUnit.config.current.testName` to pass the current test's name on to another tool

```js
QUnit.test("some test", function() {
// a few regular assertions
// then a call to another tool
speedTest( QUnit.config.current.testName, codeUnderTest );
});
```

---

Add a new checkbox to the toolbar, using the `urlConfig` property. This assumes there's other code on the page that will check the `QUnit.config.min` property to react to the selection.

```js
QUnit.config.urlConfig.push({
id: "min",
label: "Minified source",
tooltip: "Load minified source files instead of the regular unminified ones."
});
```

---

Add a dropdown to the toolbar, using the `urlConfig` property. This assumes there's other code on the page that will check the `QUnit.config.jquery` property to react to the selection, loading the appropiate jQuery Core version.

```js
QUnit.config.urlConfig.push({
id: "jquery",
label: "jQuery version",
value: [ "1.7.2", "1.8.3", "1.9.1" ],
tooltip: "What jQuery Core version to test against"
});
```

---

Preconfiguring QUnit

If you want to configure QUnit before it is loaded, you can introduce the global variable `QUnit` with the property `config` specified. All other properties of the QUnit object will be ignored. In the config properties you may specify any of the allowed QUnit.config values.

```js
// QUnit is not yet loaded here
window.QUnit = {
config: {
autoStart: false,
noGlobals: true,
}
};
```
71 config/QUnit.dump.parse.md
View file
@@ -0,0 +1,71 @@
---
layout: default
categories: [config]
title: QUnit.dump.parse
description: Advanced and extensible data dumping for JavaScript
---

## `QUnit.dump.parse( data )`

Advanced and extensible data dumping for JavaScript

| name | description |
|--------------------|--------------------------------------|
| `data` | Data structure or Object to parse. |

This method does string serialization by parsing data structures and objects. It parses DOM elements to a string representation of their outer HTML. By default, nested structures will be displayed up to five levels deep. Anything beyond that is replaced by `[object Object]` and `[object Array]` placeholders.

If you need more or less output, change the value of `QUnit.dump.maxDepth`, representing how deep the elements should be parsed.

> NOTE: This method used to be in `QUnit.jsDump`, which was changed to `QUnit.dump`. The old property will be removed in QUnit 3.0.
### Examples

The following example is used on [grunt-contrib-qunit][] to send messages from QUnit to PhantomJS.

[grunt-contrib-qunit]: https://github.com/gruntjs/grunt-contrib-qunit/blob/7568f3ba04a5790b2c92f44da3ce5c7bdc1c7491/phantomjs/bridge.js#L24-L33

```js
QUnit.log(function( obj ) {
// Parse some stuff before sending it.
var actual = QUnit.dump.parse( obj.actual );
var expected = QUnit.dump.parse( obj.expected );
// Send it.
sendMessage( "qunit.log", obj.result, actual, expected, obj.message, obj.source );
});
```

---

This example shows the parsed output of a simple JS object with a DOM reference.

```js
var qHeader = document.getElementById( "qunit-header" ),
parsed = QUnit.dump.parse( qHeader );
console.log( parsed );
// Logs: "<h1 id=\"qunit-header\"></h1>"
```

---

Limit output to one or two levels

```js
var input = {
parts: {
front: [],
back: []
}
};
QUnit.dump.maxDepth = 1;
console.log( QUnit.dump.parse( input ) );
// Logs: { "parts": [object Object] }
QUnit.dump.maxDepth = 2;
console.log( QUnit.dump.parse( input ) );
// Logs: { "parts": { "back": [object Array], "front": [object Array] } }
```
41 config/QUnit.extend.md
View file
@@ -0,0 +1,41 @@
---
layout: default
categories: [config]
title: QUnit.extend
description: Copy the properties defined by the <code>mixin</code> object into the <code>target</code> object
---

## `QUnit.extend( target, mixin )`

Copy the properties defined by the `mixin` object into the `target` object

| name | description |
|--------------------|--------------------------------------|
| `target` | An object whose properties are to be modified |
| `mixin` | An object describing which properties should be modified |

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.

### Example

Define a custom `mod2` assertion that tests if the provided numbers are equivalent in modulo 2.

```js
QUnit.test( "QUnit.extend", function( assert ) {
var base = {
a: 1,
b: 2,
z: 3
};
QUnit.extend( base, {
b: 2.5,
c: 3,
z: undefined
} );
assert.equal( base.a, 1, "Unspecified values are not modified" );
assert.equal( base.b, 2.5, "Existing values are updated" );
assert.equal( base.c, 3, "New values are defined" );
assert.ok( !( "z" in base ), "Values specified as `undefined` are removed" );
});
```
24 config/QUnit.push.md
View file
@@ -0,0 +1,24 @@
---
layout: default
categories: [config]
title: QUnit.push
status: deprecated
description: "<strong>DEPRECATED</strong> Report the result of a custom assertion"
---

## `QUnit.push( result, actual, expected, message )`

__DEPRECATED__: Report the result of a custom assertion

| name | description |
|--------------------|--------------------------------------|
| `result` (boolean) | Result of the assertion |
| `actual` | Expression being tested |
| `expected` | Known comparison value |
| `message` (string) | A short description of the assertion |

<p class="warning">This method is __deprecated__ and it's recommended to use [`pushResult`](/api/assert/pushResult/) on its direct reference in the assertion context.</p>

`QUnit.push` reflects to the current running test, and it may leak assertions in asynchronous mode. Checkout [`assert.pushResult()`](/api/assert/pushResult/) 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.
42 config/QUnit.stack.md
View file
@@ -0,0 +1,42 @@
---
layout: default
categories: [config]
title: QUnit.stack
description: Returns a single line string representing the stacktrace (call stack)
---

## `QUnit.stack( [ offset = 0 ] )`

Returns a single line string representing the stacktrace (call stack)

| name | description |
|--------------------|--------------------------------------|
| `offset` (number) | Set the stacktrace line offset. Defaults to `0` |

This method returns a single line string representing the stacktrace from where it was called. According to its offset argument, `QUnit.stack()` will return the correspondent line from the call stack.

The default offset is 0 and will return the current location where it was called.

Not all [browsers support retrieving stracktraces][browsers]. In those, `QUnit.stack()` will return `undefined`.

[browsers]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/Stack#Browser_compatibility

### Example

The stacktrace line can be used on custom assertions and reporters. The following example [logs](/api/callbacks/QUnit.log/) the line of each passing assertion.

```js
QUnit.log( function( details ) {
if ( details.result ) {
// 5 is the line reference for the assertion method, not the following line.
console.log( QUnit.stack( 5 ) );
}
} );
QUnit.test( "foo", function( assert ) {
// the log callback will report the position of the following line.
assert.ok( true );
} );
```
7 config/index.md
View file
@@ -0,0 +1,7 @@
---
layout: page
title: Configuration tools
category: config
categories:
- topics
---
359 css/styles.css
View file
@@ -0,0 +1,359 @@
//--------------------------------------------------
// Reset
// -------------------------------------------------

html, body, div, span, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, abbr, address, cite, code, del, dfn, em, img, ins, kbd, q, samp, small, strong, sub, sup, var, b, i, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, figure, footer, header, hgroup, menu, nav, section, menu, time, mark, audio, video {
margin: 0;
padding: 0;
border: 0;
outline: 0;
font-size: 100%;
vertical-align: baseline;
background: transparent;
}

body {
line-height: 1;
}

ol, ul {
list-style: none;
}

blockquote, q {
quotes: none;
}

blockquote:before, blockquote:after, q:before, q:after {
content: '';
content: none;
}

ins {
text-decoration: none;
}

del {
text-decoration: line-through;
}

table {
border-collapse: collapse;
border-spacing: 0;
}

article, aside, figure, footer, header, hgroup, nav, section {
display: block;
}

html {
-ms-text-size-adjust: 100%;
-webkit-text-size-adjust: 100%;
}

img {
width: 100%;
}

.skip,
.a11y {
left: -1000em;
overflow: hidden;
position: absolute;
top: 0;
width: 0;
}

/*---------------------------*/
/*---- Syntax Hightlight ----*/
/*---------------------------*/

/*
* GitHub style for Pygments syntax highlighter, for use with Jekyll
* Courtesy of GitHub.com
*/

.highlight pre, pre, .highlight .hll { background-color: #f8f8f8; border: 1px solid #ccc; padding: 6px 10px; border-radius: 3px; }
.highlight .c { color: #999988; font-style: italic; }
.highlight .err { color: #a61717; background-color: #e3d2d2; }
.highlight .k { font-weight: bold; }
.highlight .o { font-weight: bold; }
.highlight .cm { color: #999988; font-style: italic; }
.highlight .cp { color: #999999; font-weight: bold; }
.highlight .c1 { color: #999988; font-style: italic; }
.highlight .cs { color: #999999; font-weight: bold; font-style: italic; }
.highlight .gd { color: #000000; background-color: #ffdddd; }
.highlight .gd .x { color: #000000; background-color: #ffaaaa; }
.highlight .ge { font-style: italic; }
.highlight .gr { color: #aa0000; }
.highlight .gh { color: #999999; }
.highlight .gi { color: #000000; background-color: #ddffdd; }
.highlight .gi .x { color: #000000; background-color: #aaffaa; }
.highlight .go { color: #888888; }
.highlight .gp { color: #555555; }
.highlight .gs { font-weight: bold; }
.highlight .gu { color: #800080; font-weight: bold; }
.highlight .gt { color: #aa0000; }
.highlight .kc { font-weight: bold; }
.highlight .kd { font-weight: bold; }
.highlight .kn { font-weight: bold; }
.highlight .kp { font-weight: bold; }
.highlight .kr { font-weight: bold; }
.highlight .kt { color: #445588; font-weight: bold; }
.highlight .m { color: #009999; }
.highlight .s { color: #dd1144; }
.highlight .n { color: #333333; }
.highlight .na { color: teal; }
.highlight .nb { color: #0086b3; }
.highlight .nc { color: #445588; font-weight: bold; }
.highlight .no { color: teal; }
.highlight .ni { color: purple; }
.highlight .ne { color: #990000; font-weight: bold; }
.highlight .nf { color: #990000; font-weight: bold; }
.highlight .nn { color: #555555; }
.highlight .nt { color: navy; }
.highlight .nv { color: teal; }
.highlight .ow { font-weight: bold; }
.highlight .w { color: #bbbbbb; }
.highlight .mf { color: #009999; }
.highlight .mh { color: #009999; }
.highlight .mi { color: #009999; }
.highlight .mo { color: #009999; }
.highlight .sb { color: #dd1144; }
.highlight .sc { color: #dd1144; }
.highlight .sd { color: #dd1144; }
.highlight .s2 { color: #dd1144; }
.highlight .se { color: #dd1144; }
.highlight .sh { color: #dd1144; }
.highlight .si { color: #dd1144; }
.highlight .sx { color: #dd1144; }
.highlight .sr { color: #009926; }
.highlight .s1 { color: #dd1144; }
.highlight .ss { color: #990073; }
.highlight .bp { color: #999999; }
.highlight .vc { color: teal; }
.highlight .vg { color: teal; }
.highlight .vi { color: teal; }
.highlight .il { color: #009999; }
.highlight .gc { color: #999; background-color: #EAF2F5; }

/*---------------------------*/
/*-------- Site styles ------*/
/*---------------------------*/

* {
moz-box-sizing: border-box;
box-sizing: border-box;
}

html {
height: 100%;
}

body {
display: flex;
flex-direction: column;
font-family: 'Helvetica Neue', Helvetica, serif;
font-weight: normal;
margin: 0;
min-height: 100%;
}

img {
max-width: 100%;
}

a:link,
a:active {
border-bottom: 2px solid #e6008c;
color: #000;
font-weight: bold;
text-decoration: none;
}

a:active {
bottom: -1px;
position: relative;
}

a:hover,
a:visited {
background-color: rgba(230, 0, 140, .1);
border-bottom: 2px solid #e6008c;
color: #000;
text-decoration: none;
}

a:focus {
background-color: rgba(230, 0, 140, .1)
}

p {
font-size: .875rem;
line-height: 1.5;
}

.center {
text-align: center;
}

/*-------------------------------*/
/*---------Site wide header -----*/
/*-------------------------------*/

.site-header {
align-items: center;
background: rgb(57, 15, 57);
padding: 2em 1em;
}

.site-header-wrapper {
max-width: 1040px;
margin: 0 auto;
}

@media (min-width: 40em) {
.site-header-wrapper {
align-items: center;
display: flex;
flex-direction: row;
flex-wrap: nowrap;
}
}

.site-logo {
flex: 1 0 auto;

}

.logo {
margin: 0;
padding: 0;
}

a.logo-link:link,
a.logo-link:visited {
background: url('/api/img/logo-qunit@2x.png') no-repeat 0 0;
background-size: cover;
border: none;
display: block;
height: 66px;
text-indent: -99999px;
width: 243px;
}

a.logo-link:hover {
background-color: transparent;
border: none;
}

a.logo-link:focus {
background-color: none;
}

.site-nav {
flex: 1 0 auto;
}

.site-nav-list {
margin: 1em 0 0 0;
padding: 0;
}

@media (min-width: 40em) {
.site-nav-list {
margin: 0;
text-align: right;
}
}

.site-nav-list-item {
display: inline-block;
}

a.site-nav-list-link:link,
a.site-nav-list-link:active {
border-bottom: none;
color: #fff;
display: inline-block;
font-style: normal;
font-weight: normal;
padding: 1em 2em 1em 0;
}

a.site-nav-list-link:hover,
a.site-nav-list-link:visited {
background-color: transparent;
color: #fff;
text-decoration: underline;
}

a.site-nav-list-link:focus {
background-color: transparent;
text-decoration: underline;
}

@media (min-width: 40em) {
a.site-nav-list-link:link {
padding: 0 2em;
}
}

/*--------------------------------------------*/
/*---------- Home page ----------------*/
/*--------------------------------------------*/

.main {
/*background-color: #403B6E;*/

}

.wrapper {
max-width: 1040px;
margin: 0 auto;
padding: 1em;
display: flex;
}

@media (min-width: 65em) {
.main-content {
padding: 0;
}
}

.sidebar {
flex: 0 0 240px;
}

.sidebar-list {
padding-left: 0;
}

.sidebar-item ~ .sidebar-item{
padding-top: 1rem;
}

table {
padding: 0; }
table tr {
border-top: 1px solid #cccccc;
background-color: white;
margin: 0;
padding: 0; }
table tr:nth-child(2n) {
background-color: #f8f8f8; }
table tr th {
font-weight: bold;
border: 1px solid #cccccc;
text-align: left;
margin: 0;
padding: 6px 13px; }
table tr td {
border: 1px solid #cccccc;
text-align: left;
margin: 0;
padding: 6px 13px; }
table tr th :first-child, table tr td :first-child {
margin-top: 0; }
table tr th :last-child, table tr td :last-child {
margin-bottom: 0; }
19 entries/QUnit.assert.xml
View file

This file was deleted.

31 entries/QUnit.begin.xml
View file

This file was deleted.

191 entries/QUnit.config.xml
View file

This file was deleted.