From 78aa9bb6353eabb38e4fd4816fbc57be5c5b9f4b Mon Sep 17 00:00:00 2001 From: Robert Jackson Date: Tue, 19 Feb 2019 12:23:35 -0500 Subject: [PATCH] Update API.md for v1.4.0 release. --- API.md | 237 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 129 insertions(+), 108 deletions(-) diff --git a/API.md b/API.md index 9d6b5e502..c8db32182 100644 --- a/API.md +++ b/API.md @@ -78,6 +78,8 @@ - [setupOnerror][74] - [Parameters][75] - [Examples][76] +- [resetOnerror][77] + - [Examples][78] ## DOM Interaction Helpers @@ -101,9 +103,9 @@ to continue to emulate how actual browsers handle unfocusing a given element. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to unfocus (optional, default `document.activeElement`) +- `target` **([string][79] \| [Element][80])** the element or selector to unfocus (optional, default `document.activeElement`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### click @@ -130,14 +132,18 @@ For focusable (e.g. form control) elements the following events are triggered The exact listing of events that are triggered may change over time as needed to continue to emulate how actual browsers handle clicking a given element. -Use the `options` hash to change the parameters of the MouseEvents. +Use the `options` hash to change the parameters of the MouseEvents. You can use this to specifiy modifier keys as well. For example: + +```javascript +await click('div', { shiftKey: true }); +``` #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to click on -- `options` **[Object][80]** the options to be merged into the mouse events (optional, default `{}`) +- `target` **([string][79] \| [Element][80])** the element or selector to click on +- `options` **[Object][82]** the options to be merged into the mouse events (optional, default `{}`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### doubleClick @@ -176,10 +182,10 @@ Use the `options` hash to change the parameters of the MouseEvents. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to double-click on -- `options` **[Object][80]** the options to be merged into the mouse events (optional, default `{}`) +- `target` **([string][79] \| [Element][80])** the element or selector to double-click on +- `options` **[Object][82]** the options to be merged into the mouse events (optional, default `{}`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### fillIn @@ -189,10 +195,10 @@ events on the specified target. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to enter text into -- `text` **[string][77]** the text to fill into the target element +- `target` **([string][79] \| [Element][80])** the element or selector to enter text into +- `text` **[string][79]** the text to fill into the target element -Returns **[Promise][79]<void>** resolves when the application is settled +Returns **[Promise][81]<void>** resolves when the application is settled ### focus @@ -211,9 +217,9 @@ to continue to emulate how actual browsers handle focusing a given element. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to focus +- `target` **([string][79] \| [Element][80])** the element or selector to focus -Returns **[Promise][79]<void>** resolves when the application is settled +Returns **[Promise][81]<void>** resolves when the application is settled ### tap @@ -248,10 +254,10 @@ Use the `options` hash to change the parameters of the tap events. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to tap on -- `options` **[Object][80]** the options to be merged into the touch events (optional, default `{}`) +- `target` **([string][79] \| [Element][80])** the element or selector to tap on +- `options` **[Object][82]** the options to be merged into the touch events (optional, default `{}`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### triggerEvent @@ -259,16 +265,16 @@ Triggers an event on the specified target. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to trigger the event on -- `eventType` **[string][77]** the type of event to trigger -- `options` **[Object][80]** additional properties to be set on the event +- `target` **([string][79] \| [Element][80])** the element or selector to trigger the event on +- `eventType` **[string][79]** the type of event to trigger +- `options` **[Object][82]** additional properties to be set on the event #### Examples Using triggerEvent to Upload a file When using triggerEvent to upload a file the `eventType` must be `change` and you must pass the `options` param as an object with a key `files` containing an array of -[Blob][81]. +[Blob][83]. ```javascript @@ -279,27 +285,27 @@ triggerEvent( ); ``` -Returns **[Promise][79]<void>** resolves when the application is settled +Returns **[Promise][81]<void>** resolves when the application is settled ### triggerKeyEvent Triggers a keyboard event of given type in the target element. -It also requires the developer to provide either a string with the [`key`][82] -or the numeric [`keyCode`][83] of the pressed key. +It also requires the developer to provide either a string with the [`key`][84] +or the numeric [`keyCode`][85] of the pressed key. Optionally the user can also provide a POJO with extra modifiers for the event. #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to trigger the event on +- `target` **([string][79] \| [Element][80])** the element or selector to trigger the event on - `eventType` **(`"keydown"` \| `"keyup"` \| `"keypress"`)** the type of event to trigger -- `key` **([number][84] \| [string][77])** the `keyCode`(number) or `key`(string) of the event being triggered -- `modifiers` **[Object][80]?** the state of various modifier keys (optional, default `DEFAULT_MODIFIERS`) - - `modifiers.ctrlKey` **[boolean][85]** if true the generated event will indicate the control key was pressed during the key event (optional, default `false`) - - `modifiers.altKey` **[boolean][85]** if true the generated event will indicate the alt key was pressed during the key event (optional, default `false`) - - `modifiers.shiftKey` **[boolean][85]** if true the generated event will indicate the shift key was pressed during the key event (optional, default `false`) - - `modifiers.metaKey` **[boolean][85]** if true the generated event will indicate the meta key was pressed during the key event (optional, default `false`) +- `key` **([number][86] \| [string][79])** the `keyCode`(number) or `key`(string) of the event being triggered +- `modifiers` **[Object][82]?** the state of various modifier keys (optional, default `DEFAULT_MODIFIERS`) + - `modifiers.ctrlKey` **[boolean][87]** if true the generated event will indicate the control key was pressed during the key event (optional, default `false`) + - `modifiers.altKey` **[boolean][87]** if true the generated event will indicate the alt key was pressed during the key event (optional, default `false`) + - `modifiers.shiftKey` **[boolean][87]** if true the generated event will indicate the shift key was pressed during the key event (optional, default `false`) + - `modifiers.metaKey` **[boolean][87]** if true the generated event will indicate the meta key was pressed during the key event (optional, default `false`) -Returns **[Promise][79]<void>** resolves when the application is settled +Returns **[Promise][81]<void>** resolves when the application is settled ### typeIn @@ -315,11 +321,11 @@ per character of the passed text (this may vary on some browsers). #### Parameters -- `target` **([string][77] \| [Element][78])** the element or selector to enter text into -- `text` **[string][77]** the test to fill the element with -- `options` **[Object][80]** {delay: x} (default 50) number of milliseconds to wait per keypress (optional, default `{}`) +- `target` **([string][79] \| [Element][80])** the element or selector to enter text into +- `text` **[string][79]** the test to fill the element with +- `options` **[Object][82]** {delay: x} (default 50) number of milliseconds to wait per keypress (optional, default `{}`) -Returns **[Promise][79]<void>** resolves when the application is settled +Returns **[Promise][81]<void>** resolves when the application is settled ## DOM Query Helpers @@ -333,9 +339,9 @@ Find the first element matched by the given selector. Equivalent to calling #### Parameters -- `selector` **[string][77]** the selector to search for +- `selector` **[string][79]** the selector to search for -Returns **[Element][78]** matched element or null +Returns **[Element][80]** matched element or null ### findAll @@ -345,15 +351,15 @@ of a `NodeList`. #### Parameters -- `selector` **[string][77]** the selector to search for +- `selector` **[string][79]** the selector to search for -Returns **[Array][86]** array of matched elements +Returns **[Array][88]** array of matched elements ### getRootElement Get the root element of the application under test (usually `#ember-testing`) -Returns **[Element][78]** the root element +Returns **[Element][80]** the root element ## Routing Helpers @@ -366,18 +372,18 @@ Navigate the application to the provided URL. #### Parameters -- `url` **[string][77]** The URL to visit (e.g. `/posts`) -- `options` **[object][80]** app boot options +- `url` **[string][79]** The URL to visit (e.g. `/posts`) +- `options` **[object][82]** app boot options -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### currentRouteName -Returns **[string][77]** the currently active route name +Returns **[string][79]** the currently active route name ### currentURL -Returns **[string][77]** the applications current url +Returns **[string][79]** the applications current url ## Rendering Helpers @@ -392,7 +398,7 @@ Renders the provided template and appends it to the DOM. - `template` **CompiledTemplate** the template to render -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### clearRender @@ -400,7 +406,7 @@ Clears any templates previously rendered. This is commonly used for confirming behavior that is triggered by teardown (e.g. `willDestroyElement`). -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ## Wait Helpers @@ -415,12 +421,12 @@ interim DOM states (e.g. loading states, pending promises, etc). #### Parameters -- `selector` **[string][77]** the selector to wait for -- `options` **[Object][80]?** the options to be used (optional, default `{}`) - - `options.timeout` **[number][84]** the time to wait (in ms) for a match (optional, default `1000`) - - `options.count` **[number][84]** the number of elements that should match the provided selector (null means one or more) (optional, default `null`) +- `selector` **[string][79]** the selector to wait for +- `options` **[Object][82]?** the options to be used (optional, default `{}`) + - `options.timeout` **[number][86]** the time to wait (in ms) for a match (optional, default `1000`) + - `options.count` **[number][86]** the number of elements that should match the provided selector (null means one or more) (optional, default `null`) -Returns **[Promise][79]<([Element][78] \| [Array][86]<[Element][78]>)>** resolves when the element(s) appear on the page +Returns **[Promise][81]<([Element][80] \| [Array][88]<[Element][80]>)>** resolves when the element(s) appear on the page ### waitUntil @@ -431,19 +437,19 @@ while _not_ settled (e.g. "loading" or "pending" states). #### Parameters -- `callback` **[Function][87]** the callback to use for testing when waiting should stop -- `options` **[Object][80]?** options used to override defaults (optional, default `{}`) - - `options.timeout` **[number][84]** the maximum amount of time to wait (optional, default `1000`) - - `options.timeoutMessage` **[string][77]** the message to use in the reject on timeout (optional, default `'waitUntil timed out'`) +- `callback` **[Function][89]** the callback to use for testing when waiting should stop +- `options` **[Object][82]?** options used to override defaults (optional, default `{}`) + - `options.timeout` **[number][86]** the maximum amount of time to wait (optional, default `1000`) + - `options.timeoutMessage` **[string][79]** the message to use in the reject on timeout (optional, default `'waitUntil timed out'`) -Returns **[Promise][79]** resolves with the callback value when it returns a truthy value +Returns **[Promise][81]** resolves with the callback value when it returns a truthy value ### settled Returns a promise that resolves when in a settled state (see `isSettled` for a definition of "settled state"). -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### isSettled @@ -453,7 +459,7 @@ Settled generally means that there are no pending timers, no pending waiters, no pending AJAX requests, and no current run loop. However, new settledness metrics may be added and used as they become available. -Returns **[boolean][85]** `true` if settled, `false` otherwise +Returns **[boolean][87]** `true` if settled, `false` otherwise ### getSettledState @@ -474,8 +480,10 @@ Check various settledness metrics, and return an object with the following prope router has not been instantiated / setup for the test yet this will return `null`, if there are pending transitions, this will be `true`, otherwise `false`. - `pendingRequestCount` - The count of pending AJAX requests. +- `debugInfo` - Debug information that's combined with info return from backburner's + getDebugInfo method. -Returns **[Object][80]** object with properties for each of the metrics used to determine settledness +Returns **[Object][82]** object with properties for each of the metrics used to determine settledness ## Pause Helpers @@ -520,7 +528,7 @@ module('awesome-sauce', function(hooks) { }); ``` -Returns **[Promise][79]<void>** resolves _only_ when `resumeTest()` is invoked +Returns **[Promise][81]<void>** resolves _only_ when `resumeTest()` is invoked ### resumeTest @@ -562,17 +570,17 @@ Responsible for: #### Parameters -- `context` **[Object][80]** the context to setup -- `options` **[Object][80]?** options used to override defaults (optional, default `{}`) +- `context` **[Object][82]** the context to setup +- `options` **[Object][82]?** options used to override defaults (optional, default `{}`) - `options.resolver` **Resolver?** a resolver to use for customizing normal resolution -Returns **[Promise][79]<[Object][80]>** resolves with the context that was setup +Returns **[Promise][81]<[Object][82]>** resolves with the context that was setup ### getContext Retrive the "global testing context" as stored by `setContext`. -Returns **[Object][80]** the previously stored testing context +Returns **[Object][82]** the previously stored testing context ### setContext @@ -582,7 +590,7 @@ Generally setup automatically by `setupContext`. #### Parameters -- `context` **[Object][80]** the context to use +- `context` **[Object][82]** the context to use ### unsetContext @@ -602,11 +610,11 @@ Responsible for: #### Parameters -- `context` **[Object][80]** the context to setup -- `options` **[Object][80]?** options used to override defaults - - `options.waitForSettled` **[boolean][85]** should the teardown wait for `settled()`ness (optional, default `true`) +- `context` **[Object][82]** the context to setup +- `options` **[Object][82]?** options used to override defaults + - `options.waitForSettled` **[boolean][87]** should the teardown wait for `settled()`ness (optional, default `true`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### setupRenderingContext @@ -626,9 +634,9 @@ Responsible for: #### Parameters -- `context` **[Object][80]** the context to setup for rendering +- `context` **[Object][82]** the context to setup for rendering -Returns **[Promise][79]<[Object][80]>** resolves with the context that was setup +Returns **[Promise][81]<[Object][82]>** resolves with the context that was setup ### teardownRenderingContext @@ -641,11 +649,11 @@ Responsible for: #### Parameters -- `context` **[Object][80]** the context to setup -- `options` **[Object][80]?** options used to override defaults - - `options.waitForSettled` **[boolean][85]** should the teardown wait for `settled()`ness (optional, default `true`) +- `context` **[Object][82]** the context to setup +- `options` **[Object][82]?** options used to override defaults + - `options.waitForSettled` **[boolean][87]** should the teardown wait for `settled()`ness (optional, default `true`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### getApplication @@ -676,9 +684,9 @@ Sets up the basic framework used by application tests. #### Parameters -- `context` **[Object][80]** the context to setup +- `context` **[Object][82]** the context to setup -Returns **[Promise][79]<[Object][80]>** resolves with the context that was setup +Returns **[Promise][81]<[Object][82]>** resolves with the context that was setup ### teardownApplicationContext @@ -686,11 +694,11 @@ Used by test framework addons to tear down the provided context after testing is #### Parameters -- `context` **[Object][80]** the context to setup -- `options` **[Object][80]?** options used to override defaults - - `options.waitForSettled` **[boolean][85]** should the teardown wait for `settled()`ness (optional, default `true`) +- `context` **[Object][82]** the context to setup +- `options` **[Object][82]?** options used to override defaults + - `options.waitForSettled` **[boolean][87]** should the teardown wait for `settled()`ness (optional, default `true`) -Returns **[Promise][79]<void>** resolves when settled +Returns **[Promise][81]<void>** resolves when settled ### validateErrorHandler @@ -705,7 +713,7 @@ everything is on fire... #### Parameters -- `callback` **[Function][87]** the callback to validate (optional, default `Ember.onerror`) +- `callback` **[Function][89]** the callback to validate (optional, default `Ember.onerror`) #### Examples @@ -721,17 +729,17 @@ test('Ember.onerror is functioning properly', function(assert) { }); ``` -Returns **[Object][80]** object with `isValid` and `message` +Returns **[Object][82]** object with `isValid` and `message` ## setupOnerror Sets the `Ember.onerror` function for tests. This value is intended to be reset after - each test to ensure correct test isolation. To reset, you should simply call `setupOnerror` - without an `onError` argument. +each test to ensure correct test isolation. To reset, you should simply call `setupOnerror` +without an `onError` argument. ### Parameters -- `onError` **[Function][87]** the onError function to be set on Ember.onerror +- `onError` **[Function][89]** the onError function to be set on Ember.onerror ### Examples @@ -741,16 +749,25 @@ Example implementation for `ember-qunit` or `ember-mocha` ```javascript import { setupOnerror } from '@ember/test-helpers'; - test('Ember.onerror is stubbed properly', function(assert) { - setupOnerror(function(err) { - assert.ok(err); - }); - }); +test('Ember.onerror is stubbed properly', function(assert) { + setupOnerror(function(err) { + assert.ok(err); + }); +}); +``` + +## resetOnerror - // To reset `Ember.onerror` for each test to ensure isolation - QUnit.testDone(function() { - setupOnerror(); - }); +Resets `Ember.onerror` to the value it originally was at the start of the test run. + +### Examples + +```javascript +import { resetOnerror } from '@ember/test-helpers'; + +QUnit.testDone(function() { + resetOnerror(); +}) ``` [1]: #dom-interaction-helpers @@ -905,24 +922,28 @@ import { setupOnerror } from '@ember/test-helpers'; [76]: #examples-3 -[77]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[77]: #resetonerror + +[78]: #examples-4 + +[79]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[78]: https://developer.mozilla.org/docs/Web/API/Element +[80]: https://developer.mozilla.org/docs/Web/API/Element -[79]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise +[81]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise -[80]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[82]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[81]: https://developer.mozilla.org/en-US/docs/Web/API/Blob +[83]: https://developer.mozilla.org/en-US/docs/Web/API/Blob -[82]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values +[84]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values -[83]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode +[85]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode -[84]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[86]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[85]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[87]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[86]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[88]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[87]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[89]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function