UNPKG

6.34 kBMarkdownView Raw
1# ember-qunit
2
3[![Latest NPM release][npm-badge]][npm-badge-url]
4[![CI Build Status][ci-badge]][ci-badge-url]
5
6[npm-badge]: https://img.shields.io/npm/v/ember-qunit.svg
7[npm-badge-url]: https://www.npmjs.com/package/ember-qunit
8[ci-badge]: https://github.com/emberjs/ember-qunit/workflows/CI/badge.svg
9[ci-badge-url]: https://github.com/emberjs/ember-qunit/actions?query=workflow%3ACI
10
11ember-qunit simplifies testing of Ember applications with
12[QUnit](https://qunitjs.com/) by providing QUnit-specific wrappers around the
13helpers contained in
14[ember-test-helpers](https://github.com/emberjs/ember-test-helpers).
15
16
17Requirements
18------------------------------------------------------------------------------
19
20* Ember.js v3.28 or above
21* Ember CLI v3.28 or above
22* Node.js v14 or above
23- TypeScript 4.8 and 4.9
24 - SemVer policy: [simple majors](https://www.semver-ts.org/#simple-majors)
25 - The public API is defined by the [Usage][#usage] section below.
26
27If you need support for Node 13 or older Ember CLI versions please use v4.x
28of this addon.
29
30
31Installation
32------------------------------------------------------------------------------
33
34`ember-qunit` is an [Ember CLI](http://www.ember-cli.com/) addon, so install it
35as you would any other addon:
36
37```sh
38$ ember install ember-qunit
39```
40
41Some other addons are detecting the test framework based on the installed
42addon names and are expecting `ember-cli-qunit` instead. If you have issues
43with this then `ember install ember-cli-qunit`, which should work exactly
44the same.
45
46Upgrading
47------------------------------------------------------------------------------
48
49For instructions how to upgrade to the latest version, please read our
50[Migration Guide](docs/migration.md).
51
52Usage
53------------------------------------------------------------------------------
54
55The following section describes the use of ember-qunit with the latest modern
56Ember testing APIs, as laid out in the RFCs
57[232](https://github.com/emberjs/rfcs/blob/master/text/0232-simplify-qunit-testing-api.md)
58and
59[268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md).
60
61For the older APIs have a look at our [Legacy Guide](docs/legacy.md).
62
63### Setting the Application
64
65Your `tests/test-helper.js` file should look similar to the following, to
66correctly setup the application required by `@ember/test-helpers`:
67
68```javascript
69import Application from '../app';
70import config from '../config/environment';
71import { setApplication } from '@ember/test-helpers';
72import { start } from 'ember-qunit';
73
74setApplication(Application.create(config.APP));
75
76start();
77```
78
79Also make sure that you have set `ENV.APP.autoboot = false;` for the `test`
80environment in your `config/environment.js`.
81
82### Setup Tests
83
84The `setupTest()` function can be used to setup a unit test for any kind
85of "module/unit" of your application that can be looked up in a container.
86
87It will setup your test context with:
88
89* `this.owner` to interact with Ember's [Dependency Injection](https://guides.emberjs.com/v3.0.0/applications/dependency-injection/)
90 system
91* `this.set()`, `this.setProperties()`, `this.get()`, and `this.getProperties()`
92* `this.pauseTest()` method to allow easy pausing/resuming of tests
93
94For example, the following is a unit test for the `SidebarController`:
95
96```javascript
97import { module, test } from 'qunit';
98import { setupTest } from 'ember-qunit';
99
100module('SidebarController', function(hooks) {
101 setupTest(hooks);
102
103 // Replace this with your real tests.
104 test('exists', function() {
105 let controller = this.owner.lookup('controller:sidebar');
106 assert.ok(controller);
107 });
108});
109```
110
111
112### Setup Rendering Tests
113
114The `setupRenderingTest()` function is specifically designed for tests that
115render arbitrary templates, including components and helpers.
116
117It will setup your test context the same way as `setupTest()`, and additionally:
118
119* Initializes Ember's renderer to be used with the
120 [Rendering helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#rendering-helpers),
121 specifically `render()`
122* Adds `this.element` to your test context which returns the DOM element
123 representing the wrapper around the elements that were rendered via
124 `render()`
125* sets up the [DOM Interaction Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#dom-interaction-helpers)
126 from `@ember/test-helpers` (`click()`, `fillIn()`, ...)
127
128```javascript
129import { module, test } from 'qunit';
130import { setupRenderingTest } from 'ember-qunit';
131import { render } from '@ember/test-helpers';
132import hbs from 'htmlbars-inline-precompile';
133
134module('GravatarImageComponent', function(hooks) {
135 setupRenderingTest(hooks);
136
137 test('renders', async function() {
138 await render(hbs`{{gravatar-image}}`);
139 assert.ok(this.element.querySelector('img'));
140 });
141});
142```
143
144### Setup Application Tests
145
146The `setupApplicationTest()` function can be used to run tests that interact
147with the whole application, so in most cases acceptance tests.
148
149On top of `setupTest()` it will:
150
151* Boot your application instance
152* Set up all the [DOM Interaction Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#dom-interaction-helpers)
153 (`click()`, `fillIn()`, ...) as well as the [Routing Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#routing-helpers)
154 (`visit()`, `currentURL()`, ...) from `@ember/test-helpers`
155
156```javascript
157import { module, test } from 'qunit';
158import { setupApplicationTest } from 'ember-qunit';
159import { visit, currentURL } from '@ember/test-helpers';
160
161module('basic acceptance test', function(hooks) {
162 setupApplicationTest(hooks);
163
164 test('can visit /', async function(assert) {
165 await visit('/');
166 assert.equal(currentURL(), '/');
167 });
168});
169```
170
171
172Contributing
173------------------------------------------------------------------------------
174
175### Installation
176
177* `git clone <repository-url>`
178* `cd ember-qunit`
179* `npm install`
180
181### Running tests
182
183* `npm test` (Runs `ember try:each` to test your addon against multiple Ember versions)
184* `ember test`
185* `ember test --server`
186
187### Running the dummy application
188
189* `ember serve`
190* Visit the dummy application at [http://localhost:4200](http://localhost:4200).
191
192For more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/).