Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 39 ยท Testing

Testing Ember Apps

Learn how Ember testing is organized: QUnit modules, the three test types, ember test commands, qunit-dom assertions, async settledness, and a runnable mini test runner.

Ember treats testing as part of the framework, not an afterthought. Every ember generate command creates a matching test file, the test runner is built in, and the framework knows how to wait for your app to finish its work before you check the result. A new Ember app can run its whole test suite with a single command, in a real browser.

This lesson gives you the map: the three kinds of tests, how the QUnit structure works, the commands you run, the qunit-dom assertions, and the idea of settledness that makes async tests reliable. The next two lessons go deep on rendering tests and on acceptance and unit tests.

Real Ember vs stand-in. File-named blocks are real Ember tests and read-only here (the site cannot run Ember or a browser test runner). The runnable blocks build a small QUnit-like runner in plain JavaScript so you can practice the structure and the assertions.

The three test types

Type Setup helper What it checks Speed
Unit setupTest(hooks) one class (a service, util, route, model) in isolation, with access to the owner fastest
Rendering (integration) setupRenderingTest(hooks) one component or helper: you render it and look at the DOM fast
Acceptance (application) setupApplicationTest(hooks) the whole app: visit a URL, click, check what the user sees slowest, most realistic

A good suite has many unit and rendering tests and a smaller number of acceptance tests for the main user journeys (sign in, check out, publish a post). The test files live under tests/unit, tests/integration and tests/acceptance.

flowchart TD
  A["Acceptance: whole app, few tests"] --> B["Rendering: one component, many tests"]
  B --> C["Unit: one class or function, most tests"]

The usual pyramid: the closer to the bottom, the faster and the more numerous.

Anatomy of a test file

Ember uses QUnit: a module groups tests, hooks run set-up code, and test contains assertions. Here is a unit test for a service:

tests/unit/services/shopping-cart-test.js

JavaScript
import { module, test } from 'qunit';
import { setupTest } from 'ember-qunit';

module('Unit | Service | shopping-cart', function (hooks) {
  setupTest(hooks);

  test('it counts items', function (assert) {
    const cart = this.owner.lookup('service:shopping-cart');

    cart.add({ name: 'Tea', price: 4 });
    cart.add({ name: 'Cake', price: 6 });

    assert.strictEqual(cart.count, 2, 'two items were added');
    assert.deepEqual(cart.items.map((i) => i.name), ['Tea', 'Cake']);
  });
});

Points to notice:

  • setupTest(hooks) gives each test a fresh application instance as this.owner. Services are singletons per owner, so tests never share state.
  • Use function () {}, not arrow functions, for module and test callbacks, so that this is the test context.
  • The assertion message is optional but makes failures readable.

Common QUnit assertions

Assertion Meaning
assert.ok(value) truthy
assert.notOk(value) falsy
assert.strictEqual(a, b) a === b (prefer this over equal)
assert.deepEqual(a, b) same contents for arrays/objects
assert.throws(fn, /pattern/) fn must throw an error matching the pattern
assert.expect(n) exactly n assertions must run
assert.step('x') and assert.verifySteps([...]) verify that things happened in order

assert.step/verifySteps is excellent for async flows and for "was this called" checks without a mocking library.

qunit-dom

New Ember apps include qunit-dom, which adds readable DOM assertions through assert.dom(selector):

JavaScript
assert.dom('h1').hasText('Welcome');
assert.dom('[data-test-item]').exists({ count: 3 });
assert.dom('button').isDisabled();
assert.dom('input').hasValue('Ada');
assert.dom('.error').doesNotExist();
assert.dom('a').hasAttribute('href', '/about');
assert.dom('li').hasClass('active');

Failure messages describe the element and the expectation, which is far clearer than assert.ok(find(...)).

Select elements with data-test-* attributes (<li data-test-item>), not with CSS classes. Designers change classes often; test attributes exist only to be found by tests.

A QUnit-shaped runner you can run

To see what module, hooks.beforeEach and assert do, here is a tiny runner built from scratch. It is a teaching model, but the API shape matches what you write in Ember.

JS Stand-in: a mini QUnit

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second test passes because the beforeEach hook gave it a fresh cart, which mirrors how setupTest provides a fresh owner. The last test fails deliberately so you can see the failure format.

Running tests

Command What it does
ember test build and run the whole suite once (headless Chrome by default in CI)
ember test --server re-run automatically when files change
ember test --filter "cart" run only tests whose module or test name contains the text
ember test --module "Unit | Service | cart" run one module by its full name
ember serve then open /tests run tests in your normal browser with the interactive UI

Recent app blueprints that use Vite run the same suite through npm test (which calls ember test). The browser UI at /tests is the best way to debug: you can filter, pause with await pauseTest() and inspect the page. In the UI, "Dev mode" shows the app next to the results.

Settledness: why Ember tests are rarely flaky

Many testing tools make you sprinkle sleep calls or waitFor conditions. Ember's test helpers instead wait for the app to be settled. The app is settled when:

  • no run loop work is pending (timers scheduled through Ember, autoruns),
  • no fetch/AJAX requests started through tracked ones are in flight (jQuery/fetch through test waiters),
  • no pending test waiters (registered by your code or addons) are active,
  • and no router transition is running.

click, fillIn, visit and render all return promises that resolve after the app settles. That is why you write await click('button') and then assert directly.

For your own async work, register a test waiter so tests wait for it:

JavaScript
import { waitForPromise } from '@ember/test-waiters';

async load() {
  const data = await waitForPromise(fetch('/api/items').then((r) => r.json()));
  this.items = data;
}

Without a waiter, await settled() might return while your request is still running, and the assertion fires too early. The deterministic stand-in below counts pending work and resolves when it reaches zero.

JS Stand-in: a settled() with test waiters

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What to test, and what not to

  • Test behavior a user or caller depends on: what is shown after a click, what a service returns, what a helper formats.
  • Do not test the framework: you do not need a test proving @tracked re-renders.
  • Prefer one clear failure over many assertions in one giant test; name tests like sentences ("it shows an error when the password is empty").
  • Keep tests independent. They run in random-looking order and each gets its own fresh app.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which test type is best for checking that a single component renders the right text for its arguments?

    Rendering tests render one component or helper and assert on the DOM quickly. Acceptance tests are for whole-app flows.
  2. 2. Why should test callbacks in Ember use function () {} instead of arrow functions?

    QUnit binds the test context as this. An arrow function would capture the surrounding this instead.
  3. 3. What does it mean when the app is settled?

    Test helpers wait for settledness, which removes most manual waiting and timing flakiness.
  4. 4. Which selector style is recommended for finding elements in tests?

    Test attributes do not change with styling work, so tests do not break during redesigns.

Summary

  • Ember has unit (setupTest), rendering (setupRenderingTest) and acceptance (setupApplicationTest) tests, all written with QUnit.
  • Each test gets a fresh owner, so services never leak state between tests.
  • qunit-dom gives readable DOM assertions; find elements with data-test-* attributes.
  • Test helpers wait for settledness; register test waiters for your own async work.
  • Run with ember test, filter with --filter, debug in the browser at /tests.

Next: Rendering Tests