assert.expect()

version added: 1.0.0.

Description

expect( amount )

Specify how many assertions are expected in a test.

This is most commonly used as assert.expect(0), which indicates that a test may pass without making any assertions. This means the test is only used to verify that the code runs to completion, without any uncaught errors. This is is essentially the inverse of assert.throws().

This 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 the assert.verifySteps() or assert.async() methods instead. If you’re using these stricter methods already, consider removing the assert.expect() call. See also the require-expect “never-except-zero” rule of the eslint-plugin-qunit package.

Changelog

Migration guide

If you use assert.expect() in combination with assert.step() and assert.verifySteps() in the same test, you previously counted both the steps and the verification of the steps. In QUnit 3.0 this changes to count assert.verifySteps() as one assertion instead (#1226).

Before, on QUnit 2.x without QUnit.config.countStepsAsOne:

QUnit.test('example', async function (assert) {
  assert.expect(6);

  MyWordParser.on('noun', function (word) {
    assert.step(word); // 1, 2, 3, 4
  });
  var song = await MyWordParser.sing('My Favorite Things', { lines: 1 });

  assert.true(song.finished, 'finished'); // 5
  assert.verifySteps([ // 6
    'Raindrops',
    'roses',
    'whiskers',
    'kittens'
  ]);
});

After:

QUnit.test('example', async function (assert) {
  assert.expect(2);

  MyWordParser.on('noun', function (word) {
    assert.step(word);
  });
  var song = await MyWordParser.sing('My Favorite Things', { lines: 1 });

  assert.true(song.finished, 'finished'); // 1
  assert.verifySteps([ // 2
    'Raindrops',
    'roses',
    'whiskers',
    'kittens'
  ]);
});

Examples

Example: No assertions

A test without any assertions:

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.

QUnit.test('example', function (assert) {
  assert.expect(0);

  var android = new Robot(database);
  android.run();

  database.assertNoOpenConnections();
});

Example: Explicit count

Fail the test if the test did not complete an exact assertion count.

It is recommended to test callback code with assert.verifySteps() instead, as replacement for relying on assert.expect(). See also the require-expect “never-except-zero” rule of the eslint-plugin-qunit package.

QUnit.test('example', function (assert) {
  assert.expect(2);

  function calc (x, operation) {
    return operation(x);
  }

  let result = calc(2, function (x) {
    assert.true(true, 'calc() calls operation function');
    return x * x;
  });

  assert.strictEqual(result, 4, '2 squared equals 4');
});