Ember.Test Class
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.
Item Index
Methods
- checkWaiters static
- click
- currentPath
- currentRouteName
- currentURL
- fillIn
- find
- findWithAssert
- injectTestHelpers
- keyEvent
- onInjectHelpers
- pauseTest
- promise
- registerAsyncHelper
- registerHelper
- registerWaiter
- removeTestHelpers
- resolve
- resumeTest
- setupForTesting
- setupForTesting
- testCheckboxClick
- triggerEvent
- unregisterHelper
- unregisterWaiter
- visit
- wait
Properties
Methods
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
Clicks an element and triggers any actions triggered by the element's click
event.
Example:
click('.some-jQuery-selector').then(function() {
// assert something
});
Parameters:
-
selector
StringjQuery selector for finding element on the DOM
-
context
ObjectA DOM Element, Document, or jQuery to use as context
Returns:
currentPath
()
Object
public
Returns the current path.
Example:
function validateURL() {
equal(currentPath(), 'some.path.index', "correct path was transitioned into.");
}
click('#some-link-id').then(validateURL);
Returns:
The currently active path.
currentRouteName
()
Object
public
Returns the currently active route name. Example:
function validateRouteName() {
equal(currentRouteName(), 'some.path', "correct route was transitioned into.");
}
visit('/some/path').then(validateRouteName)
Returns:
The name of the currently active route.
currentURL
()
Object
public
Returns the current URL.
Example:
function validateURL() {
equal(currentURL(), '/some/path', "correct URL was transitioned into.");
}
click('#some-link-id').then(validateURL);
Returns:
The currently active URL.
fillIn
-
selector
-
text
Fills in an input element with some text.
Example:
fillIn('#email', 'you@example.com').then(function() {
// assert something
});
Parameters:
Returns:
find
-
selector
-
[context]
Finds an element in the context of the app's container element. A simple alias
for app.$(selector)
.
Example:
var $el = find('.my-selector');
With the context
param:
var $el = find('.my-selector', '.parent-element-class');
Parameters:
Returns:
jQuery object representing the results of the query
findWithAssert
-
selector
-
[context]
Like find
, but throws an error if the element selector returns no results.
Example:
var $el = findWithAssert('.doesnt-exist'); // throws error
With the context
param:
var $el = findWithAssert('.selector-id', '.parent-element-class'); // assert will pass
Parameters:
Returns:
jQuery object representing the results of the query
Throws:
throws error if jQuery object returned has a length of 0
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
Simulates a key event, e.g. keypress
, keydown
, keyup
with the desired keyCode
Example:
keyEvent('.some-jQuery-selector', 'keypress', 13).then(function() {
// assert something
});
Parameters:
Returns:
onInjectHelpers
-
callback
Used to register callbacks to be fired whenever App.injectTestHelpers
is called.
The callback will receive the current application as an argument.
Example:
Ember.Test.onInjectHelpers(function() {
Ember.$(document).ajaxSend(function() {
Test.pendingRequests++;
});
Ember.$(document).ajaxComplete(function() {
Test.pendingRequests--;
});
});
Parameters:
-
callback
FunctionThe function to be called.
pauseTest
()
Object
public
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):
visit('/')
return pauseTest();
click('.btn');
Returns:
A promise that will never resolve
promise
-
resolver
-
label
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
.
registerAsyncHelper
-
name
-
helperMethod
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:
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:
Ember.Test.registerAsyncHelper('deletePost', function(app, postId) {
click('.delete-' + postId);
});
// ... in your test
visit('/post/2');
deletePost(2);
visit('/post/3');
deletePost(3);
registerHelper
-
name
-
helperMethod
-
options
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:
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.
App = Ember.Application.create();
App.injectTestHelpers();
boot();
registerWaiter
-
context
-
callback
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:
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:
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:
App.removeTestHelpers();
resolve
-
The
Replacement for Ember.RSVP.resolve
The only difference is this uses
an instance of Ember.Test.Promise
Parameters:
-
The
Mixedvalue to resolve
resumeTest
()
Void
public
Resumes a test paused by pauseTest
.
Returns:
setupForTesting
()
private
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).
setupForTesting
()
public
This hook defers the readiness of the application, so that you can start the app when your tests are ready to run. It also sets the router's location to 'none', so that the window's location will not be modified (preventing both accidental leaking of state between tests and interference with your testing framework).
Example:
App.setupForTesting();
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]
Triggers the given DOM event on the element identified by the provided selector. Example:
triggerEvent('#some-elem-id', 'blur');
This is actually used internally by the keyEvent
helper like so:
triggerEvent('#some-elem-id', 'keypress', { keyCode: 13 });
Parameters:
Returns:
unregisterHelper
-
name
Remove a previously added helper method.
Example:
Ember.Test.unregisterHelper('wait');
Parameters:
-
name
StringThe helper to remove.
unregisterWaiter
-
context
-
callback
unregisterWaiter
is used to unregister a callback that was
registered with registerWaiter
.
Parameters:
-
context
Object(optional)
-
callback
Function
visit
-
url
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:
visit('posts/index').then(function() {
// assert something
});
Parameters:
-
url
Stringthe name of the route
Returns:
wait
-
value
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:
Ember.Test.registerAsyncHelper('loginUser', function(app, username, password) {
visit('secured/path/here')
.fillIn('#username', username)
.fillIn('#password', password)
.click('.submit');
});
Parameters:
-
value
ObjectThe value to be returned.
Returns:
Properties
_helpers
Unknown
private
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:
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
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
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
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