SimpleTest framework

class SimpleTest()

SimpleTest framework object.

static SimpleTest.doesThrow(fn, name): Check that the function call throws an exception.

static SimpleTest.enableLegacyUnpartitionedStorage(): Enter this window to legacy unpartitioned storage mode. This disables Storage and cookie partitioning for this frame. This is useful where the test utilized BroadcastChannels to coordinate with opened windows and aren’t validating storage partitioning behavior.

static SimpleTest.endMonitorConsole(): Stop monitoring console output.

static SimpleTest.executeSoon(aFunc)

Executes a function shortly after the call, but lets the caller continue working (or finish).

Arguments:

aFunc (function) – Function to execute soon.

static SimpleTest.expectAssertions(min, max)

Note that the given range of assertions is to be expected. When this function is not called, 0 assertions are expected. When only one argument is given, that number of assertions are expected.

A test where we expect to have assertions (which should largely be a transitional mechanism to get assertion counts down from our current situation) can call the SimpleTest.expectAssertions() function, with either one or two arguments: one argument gives an exact number expected, and two arguments give a range. For example, a test might do one of the following:

Examples:

// Currently triggers two assertions (bug NNNNNN).
  SimpleTest.expectAssertions(2);

  // Currently triggers one assertion on Mac (bug NNNNNN).
  if (navigator.platform.indexOf("Mac") == 0) {
    SimpleTest.expectAssertions(1);
  }

  // Currently triggers two assertions on all platforms (bug NNNNNN),
  // but intermittently triggers two additional assertions (bug NNNNNN)
  // on Windows.
  if (navigator.platform.indexOf("Win") == 0) {
    SimpleTest.expectAssertions(2, 4);
  } else {
    SimpleTest.expectAssertions(2);
  }

  // Intermittently triggers up to three assertions (bug NNNNNN).
  SimpleTest.expectAssertions(0, 3);

static SimpleTest.expectChildProcessCrash(): Indicates to the test framework that the current test expects one or more crashes (from plugins or IPC documents), and that the minidumps from those crashes should be removed.

static SimpleTest.expectConsoleMessages(testfn, msgs, continuation)

Run testfn synchronously, and monitor its console output.

msgs is handled as described above for monitorConsole.

After testfn returns, console monitoring will stop, and continuation will be called asynchronously.

static SimpleTest.expectRegisteredServiceWorker(): Indicates to the test framework that this test is expected to leave a service worker registered when it finishes.

static SimpleTest.expectUncaughtException(aExpecting): Indicates to the test framework that the next uncaught exception during the test is expected, and should not cause a test failure.

static SimpleTest.finish(): Finishes the tests. This is automatically called, except when SimpleTest.waitForExplicitFinish() has been invoked.

static SimpleTest.ignoreAllUncaughtExceptions(aIgnoring): Indicates to the test framework that all of the uncaught exceptions during the test are known problems that should be fixed in the future, but which should not cause the test to fail currently.

static SimpleTest.is(a, b, name): Roughly equivalent to ok(Object.is(a, b), name)

static SimpleTest.isExpectingUncaughtException(): Returns whether the test has indicated that it expects an uncaught exception to occur.

static SimpleTest.isIgnoringAllUncaughtExceptions(): Returns whether the test has indicated that all uncaught exceptions should be ignored.

static SimpleTest.monitorConsole(continuation, msgs, forbidUnexpectedMsgs)

Monitor console output from now until endMonitorConsole is called.

Expect to receive all console messages described by the elements of msgs, an array, in the order listed in msgs; each element is an object which may have any number of the following properties:

message, errorMessage, sourceName, sourceLine, category: string or regexp lineNumber, columnNumber: number isScriptError, isWarning: boolean

Strings, numbers, and booleans must compare equal to the named property of the Nth console message. Regexps must match. Any fields present in the message but not in the pattern object are ignored.

In addition to the above properties, elements in msgs may have a forbid boolean property. When forbid is true, a failure is logged each time a matching message is received.

If forbidUnexpectedMsgs is true, then the messages received in the console must exactly match the non-forbidden messages in msgs; for each received message not described by the next element in msgs, a failure is logged. If false, then other non-forbidden messages are ignored, but all expected messages must still be received.

After endMonitorConsole is called, continuation will be called asynchronously. (Normally, you will want to pass SimpleTest.finish here.)

It is incorrect to use this function in a test which has not called SimpleTest.waitForExplicitFinish.

static SimpleTest.ok(condition, name): Something like assert.

static SimpleTest.promiseClipboardChange(aExpectedStringOrValidatorFn, aSetupFn, aFlavor, aTimeout, aExpectFailure, aDontInitializeClipboardIfExpectFailure): Promise-oriented version of waitForClipboard.

static SimpleTest.promiseFocus(aObject, expectBlankPage=false, aBlurSubframe=false)

If the page is not yet loaded, waits for the load event. If the page is not yet focused, focuses and waits for the window to be focused. If the current page is ‘about:blank’, then the page is assumed to not yet be loaded. Pass true for expectBlankPage to not make this assumption if you expect a blank page to be present.

The target object should be specified if it is different than ‘window’. The actual focused window may be a descendant window of aObject.

Arguments:

aObject (Window|browser|BrowsingContext) – Optional object to be focused, and may be any of: window - a window object to focus browser - a <browser>/<iframe> element. The top-level window within the frame will be focused. browsing context - a browsing context containing a window to focus If not specified, defaults to the global ‘window’.
expectBlankPage (boolean) – True if targetWindow.location is ‘about:blank’.
aBlurSubframe (boolean) – If true, and a subframe within the window to focus is focused, blur it so that the specified window or browsing context will receive focus events.

Returns:

The browsing context that was focused.

static SimpleTest.registerCleanupFunction(aFunc)

Register a cleanup/teardown function (which may be async) to run after all tasks have finished, before running the next test. If async (or the function returns a promise), the framework will wait for the promise/async function to resolve.

Arguments:

aFunc (function) – The cleanup/teardown function to run.

static SimpleTest.registerCurrentTaskCleanupFunction(aFunc)

Register a cleanup/teardown function (which may be async) to run after the current task has finished, before running the next task. If async (or the function returns a promise), the framework will wait for the promise/async function to resolve.

Arguments:

aFunc (function) – The cleanup/teardown function to run.

static SimpleTest.registerTaskCleanupFunction(aFunc)

Register a cleanup/teardown function (which may be async) to run after each task has finished, before running the next task. If async (or the function returns a promise), the framework will wait for the promise/async function to resolve.

Arguments:

aFunc (function) – The cleanup/teardown function to run.

static SimpleTest.report(): Makes a test report, returns it as a DIV element.

static SimpleTest.requestCompleteLog(): Force all test messages to be displayed. Only applies for the current test.

static SimpleTest.requestFlakyTimeout(reason)

Request the framework to allow usage of setTimeout(func, timeout) where timeout > 0. This is required to note that the author of the test is aware of the inherent flakiness in the test caused by that, and asserts that there is no way around using the magic timeout value number for some reason.

Use of this function is STRONGLY discouraged. Think twice before using it. Such magic timeout values could result in intermittent failures in your test, and are almost never necessary!

Arguments:

reason (String) – A string representation of the reason why the test needs timeouts.

static SimpleTest.requestLongerTimeout(factor)

Multiply the timeout the parent runner uses for this test by the given factor.

For example, in a test that may take a long time to complete, using “SimpleTest.requestLongerTimeout(5)” will give it 5 times as long to finish.

Arguments:

factor (Number) – The multiplication factor to use on the timeout for this test.

static SimpleTest.reset(): Resets any state this SimpleTest object has. This is important for browser chrome mochitests, which reuse the same SimpleTest object across a run.

static SimpleTest.runTestExpectingConsoleMessages(testfn, msgs): Wrapper around expectConsoleMessages for the case where the test has only one testfn to run.

static SimpleTest.showReport(): Shows the report in the browser

static SimpleTest.todo_is(a, b, name): Copies of is and isnot with the call to ok replaced by a call to todo.

static SimpleTest.toggle(el): Toggle element visibility

static SimpleTest.toggleByClass(cls, evt): Toggle visibility for divs with a specific class.

static SimpleTest.waitForCondition(aCond, aCallback, aErrorMsg)

Wait for a condition for a while (actually up to 3s here).

Arguments:

aCond (function) – A function returns the result of the condition
aCallback (function) – A function called after the condition is passed or timeout.
aErrorMsg (String) – The message displayed when the condition failed to pass before timeout.

static SimpleTest.waitForExplicitFinish()

Tells SimpleTest to don’t finish the test when the document is loaded, useful for asynchronous tests.

When SimpleTest.waitForExplicitFinish is called, explicit SimpleTest.finish() is required.

static SimpleTest.waitForFocus(callback, aObject, expectBlankPage): Version of promiseFocus that uses a callback. For compatibility, the callback is passed one argument, the window that was focused. If the focused window is not in the same process, null is supplied.