Ember.Test Class packages/ember-testing/lib/test.js:29


PUBLIC

This is a container for an assortment of testing related functionality:

  • Choose your default test adapter (for your framework of choice).
  • Register/Unregister additional test helpers.
  • Setup callbacks to be fired when the test helpers are injected into your application.
Show:

checkWaiters

public static

Iterates through each registered test waiter, and invokes its callback. If any waiter returns false, this method will return true indicating that the waiters have not settled yet.

This is generally used internally from the acceptance/integration test infrastructure.

click

(selector, context) RSVP.Promise public

Clicks an element and triggers any actions triggered by the element's click event.

Example:

1
2
3
click('.some-jQuery-selector').then(function() {
  // assert something
});

Parameters:

selector String
jQuery selector for finding element on the DOM
context Object
A DOM Element, Document, or jQuery to use as context

Returns:

RSVP.Promise

currentPath

Object public
Defined in packages/ember-testing/lib/helpers/current_path.js:7
Available since 1.5.0

Returns the current path.

Example:

1
2
3
4
5
function validateURL() {
equal(currentPath(), 'some.path.index', "correct path was transitioned into.");
}

click('#some-link-id').then(validateURL);

Returns:

Object
The currently active path.

currentRouteName

Object public

Returns the currently active route name. Example: javascript function validateRouteName() { equal(currentRouteName(), 'some.path', "correct route was transitioned into."); } visit('/some/path').then(validateRouteName)

Returns:

Object
The name of the currently active route.

currentURL

Object public
Defined in packages/ember-testing/lib/helpers/current_url.js:7
Available since 1.5.0

Returns the current URL.

Example:

1
2
3
4
5
function validateURL() {
equal(currentURL(), '/some/path', "correct URL was transitioned into.");
}

click('#some-link-id').then(validateURL);

Returns:

Object
The currently active URL.

fillIn

(selector, text) RSVP.Promise public

Fills in an input element with some text.

Example:

1
2
3
fillIn('#email', 'you@example.com').then(function() {
  // assert something
});

Parameters:

selector String
jQuery selector finding an input element on the DOM to fill text with
text String
text to place inside the input element

Returns:

RSVP.Promise

find

(selector, context) Object public

Finds an element in the context of the app's container element. A simple alias for app.$(selector).

Example:

1
var $el = find('.my-selector');

With the context param:

1
var $el = find('.my-selector', '.parent-element-class');

Parameters:

selector String
jQuery string selector for element lookup
context [String]
(optional) jQuery selector that will limit the selector argument to find only within the context's children

Returns:

Object
jQuery object representing the results of the query

findWithAssert

(selector, context) Object public

Like find, but throws an error if the element selector returns no results.

Example:

1
var $el = findWithAssert('.doesnt-exist'); // throws error

With the context param:

1
var $el = findWithAssert('.selector-id', '.parent-element-class'); // assert will pass

Parameters:

selector String
jQuery selector string for finding an element within the DOM
context [String]
(optional) jQuery selector that will limit the selector argument to find only within the context's children

Returns:

Object
jQuery object representing the results of the query

injectTestHelpers

public

This injects the test helpers into the helperContainer object. If an object is provided it will be used as the helperContainer. If helperContainer is not set it will default to window. If a function of the same name has already been defined it will be cached (so that it can be reset if the helper is removed with unregisterHelper or removeTestHelpers).

Any callbacks registered with onInjectHelpers will be called once the helpers have been injected.

Example: App.injectTestHelpers();

keyEvent

(selector, type, keyCode) RSVP.Promise public
Defined in packages/ember-testing/lib/helpers/key_event.js:5
Available since 1.5.0

Simulates a key event, e.g. keypress, keydown, keyup with the desired keyCode Example: javascript keyEvent('.some-jQuery-selector', 'keypress', 13).then(function() { // assert something });

Parameters:

selector String
jQuery selector for finding element on the DOM
type String
the type of key event, e.g. `keypress`, `keydown`, `keyup`
keyCode Number
the keyCode of the simulated key event

Returns:

RSVP.Promise

onInjectHelpers

(callback) public

Used to register callbacks to be fired whenever App.injectTestHelpers is called.

The callback will receive the current application as an argument.

Example:

1
2
3
4
5
6
7
8
9
Ember.Test.onInjectHelpers(function() {
  Ember.$(document).ajaxSend(function() {
    Test.pendingRequests++;
  });

  Ember.$(document).ajaxComplete(function() {
    Test.pendingRequests--;
  });
});

Parameters:

callback Function
The function to be called.

pauseTest

Object public
Defined in packages/ember-testing/lib/helpers/pause_test.js:27
Available since 1.9.0

Pauses the current test - this is useful for debugging while testing or for test-driving. It allows you to inspect the state of your application at any point. Example (The test will pause before clicking the button):

1
2
3
visit('/')
return pauseTest();
click('.btn');

Returns:

Object
A promise that will never resolve

promise

(resolver, label) public

This returns a thenable tailored for testing. It catches failed onSuccess callbacks and invokes the Ember.Test.adapter.exception callback in the last chained then.

This method should be returned by async helpers such as wait.

Parameters:

resolver Function
The function used to resolve the promise.
label String
An optional string for identifying the promise.

registerAsyncHelper

(name, helperMethod) public
Defined in packages/ember-testing/lib/test/helpers.js:43
Available since 1.2.0

registerAsyncHelper is used to register an async test helper that will be injected when App.injectTestHelpers is called.

The helper method will always be called with the current Application as the first parameter.

For example:

1
2
3
Ember.Test.registerAsyncHelper('boot', function(app) {
  Ember.run(app, app.advanceReadiness);
});

The advantage of an async helper is that it will not run until the last async helper has completed. All async helpers after it will wait for it complete before running.

For example:

1
2
3
4
5
6
7
8
9
Ember.Test.registerAsyncHelper('deletePost', function(app, postId) {
  click('.delete-' + postId);
});

// ... in your test
visit('/post/2');
deletePost(2);
visit('/post/3');
deletePost(3);

Parameters:

name String
The name of the helper method to add.
helperMethod Function

registerHelper

(name, helperMethod, options) public

registerHelper is used to register a test helper that will be injected when App.injectTestHelpers is called.

The helper method will always be called with the current Application as the first parameter.

For example:

1
2
3
Ember.Test.registerHelper('boot', function(app) {
  Ember.run(app, app.advanceReadiness);
});

This helper can later be called without arguments because it will be called with app as the first parameter.

1
2
3
App = Ember.Application.create();
App.injectTestHelpers();
boot();

Parameters:

name String
The name of the helper method to add.
helperMethod Function
options Object

registerWaiter

(context, callback) public
Defined in packages/ember-testing/lib/test/waiters.js:6
Available since 1.2.0

This allows ember-testing to play nicely with other asynchronous events, such as an application that is waiting for a CSS3 transition or an IndexDB transaction. The waiter runs periodically after each async helper (i.e. click, andThen, visit, etc) has executed, until the returning result is truthy. After the waiters finish, the next async helper is executed and the process repeats.

For example:

1
2
3
Ember.Test.registerWaiter(function() {
  return myPendingTransactions() == 0;
});

The context argument allows you to optionally specify the this with which your callback will be invoked.

For example:

1
Ember.Test.registerWaiter(MyDB, MyDB.hasPendingTransactions);

Parameters:

context Object
(optional)
callback Function

removeTestHelpers

public

This removes all helpers that have been registered, and resets and functions that were overridden by the helpers.

Example:

1
App.removeTestHelpers();

resolve

(The) public
Defined in packages/ember-testing/lib/test/promise.js:35
Available since 1.2.0

Replacement for Ember.RSVP.resolve The only difference is this uses an instance of Ember.Test.Promise

Parameters:

The Mixed
value to resolve

resumeTest

Void public

Resumes a test paused by pauseTest.

Returns:

Void

setupForTesting

private
Inherited from Ember.Test but overwritten in packages/ember-testing/lib/setup_for_testing.js:17
Available since 1.5.0

Sets Ember up for testing. This is useful to perform basic setup steps in order to unit test.

Use App.setupForTesting to perform integration tests (full application testing).

testCheckboxClick

private

This method creates a checkbox and triggers the click event to fire the passed in handler. It is used to correct for a bug in older versions of jQuery (e.g 1.8.3).

triggerEvent

(selector, context, type, options) RSVP.Promise public

Triggers the given DOM event on the element identified by the provided selector. Example: javascript triggerEvent('#some-elem-id', 'blur'); This is actually used internally by the keyEvent helper like so: javascript triggerEvent('#some-elem-id', 'keypress', { keyCode: 13 });

Parameters:

selector String
jQuery selector for finding element on the DOM
context [String]
jQuery selector that will limit the selector argument to find only within the context's children
type String
The event type to be triggered.
options [Object]
The options to be passed to jQuery.Event.

Returns:

RSVP.Promise

unregisterHelper

(name) public

Remove a previously added helper method.

Example:

1
Ember.Test.unregisterHelper('wait');

Parameters:

name String
The helper to remove.

unregisterWaiter

(context, callback) public
Defined in packages/ember-testing/lib/test/waiters.js:49
Available since 1.2.0

unregisterWaiter is used to unregister a callback that was registered with registerWaiter.

Parameters:

context Object
(optional)
callback Function

visit

(url) RSVP.Promise public

Loads a route, sets up any controllers, and renders any templates associated with the route as though a real user had triggered the route change while using your app.

Example:

1
2
3
visit('posts/index').then(function() {
  // assert something
});

Parameters:

url String
the name of the route

Returns:

RSVP.Promise

wait

(value) RSVP.Promise public
Defined in packages/ember-testing/lib/helpers/wait.js:10
Available since 1.0.0

Causes the run loop to process any pending events. This is used to ensure that any async operations from other helpers (or your assertions) have been processed.

This is most often used as the return value for the helper functions (see 'click', 'fillIn','visit',etc). However, there is a method to register a test helper which utilizes this method without the need to actually call wait() in your helpers.

The wait helper is built into registerAsyncHelper by default. You will not need to return app.testHelpers.wait(); - the wait behavior is provided for you.

Example:

1
2
3
4
5
6
Ember.Test.registerAsyncHelper('loginUser', function(app, username, password) {
  visit('secured/path/here')
    .fillIn('#username', username)
    .fillIn('#password', password)
    .click('.submit');
});

Parameters:

value Object
The value to be returned.

Returns:

RSVP.Promise
Show:

_helpers

private
Defined in packages/ember-testing/lib/test.js:42
Available since 1.7.0

Hash containing all known test helpers.

adapter

{Class} The adapter to be used. public

Used to allow ember-testing to communicate with a specific testing framework.

You can manually set it before calling App.setupForTesting().

Example:

1
Ember.Test.adapter = MyCustomAdapter.create()

If you do not set it, ember-testing will default to Ember.Test.QUnitAdapter.

Default: Ember.Test.QUnitAdapter

helperContainer

{Object} The object to be used for test helpers. private
Defined in packages/ember-testing/lib/ext/application.js:84
Available since 1.2.0

This will be used as the container to inject the test helpers into. By default the helpers are injected into window.

Default: window

originalMethods

{Object} private
Defined in packages/ember-testing/lib/ext/application.js:29
Available since 1.3.0

This property will contain the original methods that were registered on the helperContainer before injectTestHelpers is called.

When removeTestHelpers is called, these methods are restored to the helperContainer.

Default: {}

testHelpers

{Object} public

This property contains the testing helpers for the current application. These are created once you call injectTestHelpers on your Ember.Application instance. The included helpers are also available on the window object by default, but can be used from this object on the individual application also.

Default: {}

testing

{Boolean} public
Defined in packages/ember-testing/lib/ext/application.js:45
Available since 1.3.0

This property indicates whether or not this application is currently in testing mode. This is set when setupForTesting is called on the current application.

Default: false