Testing Components

Components are a great way to create powerful, interactive, and self-contained custom HTML elements. It is important to test the component's methods and the user's interaction with the component.

Imagine you have the following component that changes its title when a button is clicked on:

You can follow along by generating your own component with ember generate component magic-title.

import Component from '@glimmer/component';
import { action } from '@ember/object';

export default class MagicTitleComponent extends Component {
  title = 'Hello World';

  @action
  updateTitle() {
    this.set('title', 'This is Magic');
  }
}

<h2>{{this.title}}</h2>

<button type="button" class="title-button" {{on "click" this.updateTitle}}>
  Update Title
</button>

And our test might look like this:

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { click, render } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';

module('Integration | Component | magic-title', function(hooks) {
  setupRenderingTest(hooks);

  test('should update title on button click', async function(assert) {
    assert.expect(2);

    await render(hbs`<MagicTitle />`);

    assert.equal(this.element.querySelector('h2').textContent.trim(), 'Hello World', 'initial text is hello world');

    //Click on the button
    await click('.title-button');

    assert.equal(this.element.querySelector('h2').textContent.trim(), 'This is Magic', 'title changes after click');
  });
});

Note how we make use of the click helper from ember-test-helpers to interact with the component DOM to trigger the updateTitle action. You can find many other helpful helpers for simulating user interaction in rendering tests in the API documentation of ember-test-helpers.

Components starting in Ember 2 utilize closure actions. Closure actions allow components to directly invoke functions provided by outer components.

For example, imagine you have a comment form component that invokes a submitComment action when the form is submitted, passing along the form's data:

You can follow along by generating your own component with ember generate component comment-form.

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

export default class CommentFormComponent extends Component {
  @tracked comment = '';

  @action
  submitComment() {
    this.args.submitComment({ comment: this.comment });
  }
}

<form {{action "submitComment" on="submit"}}>
  <label for="comment">Comment:</label>
  <Textarea @id="comment" @value={{this.comment}} />
  <input class="comment-input" type="submit" value="Submit"/>
</form>

Here's an example test that asserts that the specified externalAction function is invoked when the component's internal submitComment action is triggered by making use of a test double (dummy function). assert.expect(1) at the top of the test makes sure that the assertion inside the external action is called:

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { click, fillIn, render } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';

module('Integration | Component | comment-form', function(hooks) {
  setupRenderingTest(hooks);

  test('should trigger external action on form submit', async function(assert) {
    assert.expect(1);

    // test double for the external action
    this.set('externalAction', (actual) => {
      let expected = { comment: 'You are not a wizard!' };
      assert.deepEqual(actual, expected, 'submitted value is passed to external action');
    });

    await render(hbs`<CommentForm @submitComment={{action externalAction}} />`);

    // fill out the form and force an onchange
    await fillIn('textarea', 'You are not a wizard!');

    // click the button to submit the form
    await click('.comment-input');
  });
});

In cases where components have dependencies on Ember services, it is possible to stub these dependencies for rendering tests. You stub Ember services by using the built-in register() function to register your stub service in place of the default.

Imagine you have the following component that uses a location service to display the city and country of your current location:

You can follow along by generating your own component with ember generate component location-indicator.

import Component from '@glimmer/component';
import { inject as service } from '@ember/service';

export default class LocationIndicatorComponent extends Component {
  @service location;

  // when the coordinates change, call the location service to get the current city and country
  get city() {
    return this.location.getCurrentCity();
  }

  get country() {
    return this.location.getCurrentCountry();
  }
}

You currently are located in {{this.city}}, {{this.country}}

To stub the location service in your test, create a local stub object that extends Service from @ember/service, and register the stub as the service your tests need in the beforeEach function. In this case we initially force location to "New York".

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';
import Service from '@ember/service';

//Stub location service
class LocationStub extends Service {
  city = 'New York';
  country = 'USA';
  currentLocation = {
    x: 1234,
    y: 5678
  };

  getCurrentCity() {
    return this.city;
  }

  getCurrentCountry() {
    return this.country;
  }
}

module('Integration | Component | location-indicator', function(hooks) {
  setupRenderingTest(hooks);

  hooks.beforeEach(function(assert) {
    this.owner.register('service:location-service', LocationStub);
  });
});

Once the stub service is registered, the test needs to check that the stub data from the service is reflected in the component output.

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';
import Service from '@ember/service';

//Stub location service
class LocationStub extends Service {
  city = 'New York';
  country = 'USA';
  currentLocation = {
    x: 1234,
    y: 5678
  };

  getCurrentCity() {
    return this.city;
  }

  getCurrentCountry() {
    return this.country;
  }
}

module('Integration | Component | location-indicator', function(hooks) {
  setupRenderingTest(hooks);

  hooks.beforeEach(function(assert) {
    this.owner.register('service:location-service', LocationStub);
  });

  test('should reveal current location', async function(assert) {
    await render(hbs`<LocationIndicator />`);
    assert.equal(this.element.textContent.trim(),
     'You currently are located in New York, USA');
  });
});

In the next example, we'll add another test that validates that the display changes when we modify the values on the service.

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';
import Service from '@ember/service';

//Stub location service
class LocationStub extends Service {
  city = 'New York';
  country = 'USA';
  currentLocation = {
    x: 1234,
    y: 5678
  };

  getCurrentCity() {
    return this.city;
  }

  getCurrentCountry() {
    return this.country;
  }
}

module('Integration | Component | location-indicator', function(hooks) {
  setupRenderingTest(hooks);

  hooks.beforeEach(function(assert) {
    this.owner.register('service:location-service', LocationStub);
  });

  test('should reveal current location', async function(assert) {
    await render(hbs`<LocationIndicator />`);
    assert.equal(this.element.textContent.trim(),
     'You currently are located in New York, USA');
  });

  test('should change displayed location when current location changes', async function (assert) {
    await render(hbs`<LocationIndicator />`);

    assert.equal(this.element.textContent.trim(),
     'You currently are located in New York, USA', 'origin location should display');

    this.locationService = this.owner.lookup('service:location-service');
    this.set('locationService.city', 'Beijing');
    this.set('locationService.country', 'China');
    this.set('locationService.currentLocation', { x: 11111, y: 222222 });

    assert.equal(this.element.textContent.trim(),
     'You currently are located in Beijing, China', 'location display should change');
  });
});

Often, interacting with a component will cause asynchronous behavior to occur, such as HTTP requests, or timers. The module @ember/test-helpers provides you with several useful helpers that will allow you to wait for any asynchronous behavior to complete that is triggered by a DOM interaction induced by those. To use them in your tests, you can await any of them to make sure that subsequent assertions are executed once the asynchronous behavior has fully settled:

await click('button.submit-button'); // clicks a button and waits for any async behavior initiated by the click to settle
assert.equal(this.element.querySelector('.form-message').textContent, 'Your details have been submitted successfully.');

Nearly all of the helpers for DOM interaction from @ember/test-helpers return a call to settled - a function that ensures that any Promises, operations in Ember's run loop, timers or network requests have already resolved. The settled function itself returns a Promise that resolves once all async operations have come to an end.

You can use settled as a helper in your tests directly and await it for all async behavior to settle deliberately.

Imagine you have a typeahead component that uses Ember.run.debounce to limit requests to the server, and you want to verify that results are displayed after typing a character.

You can follow along by generating your own component with ember generate component delayed-typeahead.

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { debounce } from '@ember/runloop';

export default class DelayedTypeaheadComponent extends Component {
  @action
  handleTyping() {
    //the fetchResults function is passed into the component from its parent
    debounce(this, this.fetchResults, this.searchValue, 250);
  }
};

<label for="search">Search</label>
<Input @id="search" @value={{this.searchValue}} @key-up={{this.handleTyping}} />
<ul>
  {{#each this.results as |result|}}
    <li class="result">{{result.name}}</li>
  {{/each}}
</ul>

In your test, use the settled helper to wait until your debounce timer is up and then assert that the page is rendered appropriately.

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render, settled } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';

module('Integration | Component | delayed-typeahead', function(hooks) {
  setupRenderingTest(hooks);

  const stubResults = [
    { name: 'result 1' },
    { name: 'result 2' }
  ];

  test('should render results after typing a term', async function(assert) {
    assert.expect(2);

    this.set('results', []);
    this.set('fetchResults', (value) => {
      assert.equal(value, 'test', 'fetch closure action called with search value');
      this.set('results', stubResults);
    });

    await render(hbs`<DelayedTypeahead @fetchResults={{this.fetchResults}} @results={{this.results}} />`);
    this.element.querySelector('input').value = 'test';
    this.element.querySelector('input').dispatchEvent(new Event('keyup'));

    await settled();

    assert.equal(this.element.querySelectorAll('.result').length, 2, 'two results rendered');
  });
});