# Class goog.testing.AsyncTestCase

code »

    goog.testing.TestCase
      └ goog.testing.AsyncTestCase

A test case that is capable of running tests the contain asynchronous logic.

## Constructor

goog.testing.AsyncTestCase ( opt_name )

Parameters
opt_name: `string=` A descriptive name for the test case.

## Classes

goog.testing.AsyncTestCase.ControlBreakingException An exception class used solely for control flow.

Show:Public Protected Private

## Type Definitions

code »goog.testing.AsyncTestCase.TopStackFuncResult_ : `{controlBreakingExceptionThrown: boolean, message: string}`
Represents result of top stack function call.

## Instance Methods

### Defined in `goog.testing.AsyncTestCase`

code »callTopOfStackFunc_ ( func ) ⇒ `!goog.testing.AsyncTestCase.TopStackFuncResult_`

Calls the given function, redirecting any exceptions to doAsyncError.

Parameters
func: `Function` The function to call.
Returns
Returns a TopStackFuncResult_.

code »continueTesting ( )

Continue with the next step in the test cycle.

code »cycleTests ( )

Starts the tests.

code »dbgLog_ ( message )

Logs the given debug message to the console (when enabled).

Parameters
message: `string` The message to log.

code »doAsyncError ( opt_e )

Handles an exception thrown by a test.

Parameters
opt_e: `*=` The exception object associated with the failure or a string.
Throws
throws a ControlBreakingException.

code »doAsyncErrorTearDown_ ( )

Calls the tearDown function, catching any errors, and then moves on to the next step in the testing cycle.

code »doExecute_ ( )

Step 3: Call test.execute().

code »doIteration_ ( )

Step 1: Move to the next test.

code »doNext_ ( )

Step 5: Call doSuccess()

code »doSetUpPage_ ( )

Sets up the test page and then waits untill the test case has been marked as ready before executing the tests.

code »doSetUp_ ( )

Step 2: Call setUp().

code »doTearDown_ ( )

Step 4: Call tearDown().

code »doTopOfStackAsyncError_ ( opt_e )

Wraps doAsyncError() for when we are sure that the test runner has no user code above it in the stack.

Parameters
opt_e: `(string|Error)=` The exception object associated with the failure or a string.

code »enableDebugLogging ( )

Enables verbose logging of what is happening inside of the AsyncTestCase.

code »endCurrentStep_ ( )

Ends the current test step and queues the next test step to run.

code »finalize ( )

Finalizes the test case, called when the tests have finished executing.

code »getCurrentStepName ( ) ⇒ `!string`

The current step name.

Returns
Step name.

code »hookAssert_ ( )

Replaces the asserts.js assert_() and fail() functions with a wrappers to catch the exceptions.

code »hookOnError_ ( )

Sets a window.onerror handler for catching exceptions that happen in async callbacks. Note that as of Safari 3.1, Safari does not support this.

code »pump_ ( opt_doFirst )

Calls the next callback when the isReady_ flag is true.

Parameters
opt_doFirst: `Function=` A function to call before pumping.
Throws
a ControlBreakingException if there were any failing steps.

code »runTests ( )

Sets up the test page and then waits until the test case has been marked as ready before executing the tests.

code »setNextStep_ ( func, name )

Sets the next function to call in our sequence of async callbacks.

Parameters
func: `Function` The function that executes the next step. name: `string` A description of the next step.

code »signal ( )

Signals once to continue with the test. If this is the last signal that the test was waiting on, call continueTesting.

code »startTimeoutTimer_ ( )

Enables the timeout timer. This timer fires unless continueTesting is called.

code »stopTimeoutTimer_ ( )

Disables the timeout timer.

code »unhookAll_ ( )

Unhooks window.onerror and _assert.

code »waitForAsync ( opt_name )

Informs the testcase not to continue to the next step in the test cycle until continueTesting is called.

Parameters
opt_name: `string=` A description of what we are waiting for.

code »waitForSignals ( times, opt_name )

Informs the testcase not to continue to the next step in the test cycle until signal is called the specified number of times. Within a test, this function behaves additively if called multiple times; the number of signals to wait for will be the sum of all expected number of signals this function was called with.

Parameters
times: `number` The number of signals to receive before continuing testing. opt_name: `string=` A description of what we are waiting for.

### Defined in `goog.testing.TestCase`

code »add ( test )

Adds a new test to the test case.

Parameters
test: `goog.testing.TestCase.Test` The test to add.

code »addNewTest ( name, ref, opt_scope )

Creates and adds a new test. Convenience function to make syntax less awkward when not using automatic test discovery.

Parameters
name: `string` The test name. ref: `!Function` Reference to the test function. opt_scope: `!Object=` Optional scope that the test function should be called in.

code »autoDiscoverLifecycle ( )

Adds any functions defined in the global scope that correspond to lifecycle events for the test case. Overrides setUp, tearDown, setUpPage, tearDownPage and runTests if they are defined.

code »autoDiscoverTests ( )

Adds any functions defined in the global scope that are prefixed with "test" to the test case.

code »clearTimeout ( id )

Clears a timeout created by `this.timeout()`.

Parameters
id: `number` A timeout id.

code »countNumFilesLoaded_ ( ) ⇒ `number`

Counts the number of files that were loaded for dependencies that are required to run the test.

Returns
The number of files loaded.

code »createTestFromAutoDiscoveredFunction ( name, ref ) ⇒ `!goog.testing.TestCase.Test`

Creates a `goog.testing.TestCase.Test` from an auto-discovered function.

Parameters
name: `string` The name of the function. ref: `function(): void` The auto-discovered function.
Returns
The newly created test.

code »doError ( test, opt_e )

Handles a test that failed.

Parameters
test: `goog.testing.TestCase.Test` The test that failed. opt_e: `*=` The exception object associated with the failure or a string.

code »doSuccess ( test )

Handles a test that passed.

Parameters
test: `goog.testing.TestCase.Test` The test that passed.

code »execute ( )

Executes each of the tests.

code »getActuallyRunCount ( ) ⇒ `number`

Returns the number of tests actually run in the test case, i.e. subtracting any which are skipped.

Returns
The number of un-ignored tests.

code »getAutoDiscoveryPrefix ( ) ⇒ `string`

Returns
The function name prefix used to auto-discover tests.

code »getBatchTime ( ) ⇒ `number`

Returns
Time since the last batch of tests was started.

code »getCount ( ) ⇒ `number`

Returns the number of tests contained in the test case.

Returns
The number of tests.

code »getGlobals ( opt_prefix ) ⇒ `!Array`

Gets list of objects that potentially contain test cases. For IE 8 and below, this is the global "this" (for properties set directly on the global this or window) and the RuntimeObject (for global variables and functions). For all other browsers, the array simply contains the global this.

Parameters
opt_prefix: `string=` An optional prefix. If specified, only get things under this prefix. Note that the prefix is only honored in IE, since it supports the RuntimeObject: http://msdn.microsoft.com/en-us/library/ff521039%28VS.85%29.aspx TODO: Remove this option.
Returns
A list of objects that should be inspected.

code »getName ( ) ⇒ `string`

Returns
The name of the test.

code »getNumFilesLoaded ( ) ⇒ `number`

Returns the number of script files that were loaded in order to run the test.

Returns
The number of script files.

code »getReport ( opt_verbose ) ⇒ `string`

Returns a string detailing the results from the test.

Parameters
opt_verbose: `boolean=` If true results will include data about all tests, not just what failed.
Returns
The results from the test.

code »getRunTime ( ) ⇒ `number`

Returns the amount of time it took for the test to run.

Returns
The run time, in milliseconds.

code »getTestResults ( ) ⇒ `!Object.<string>`

Returns the test results object: a map from test names to a list of test failures (if any exist).

Returns
Tests results object.

code »getTests ( ) ⇒ `!Array.<goog.testing.TestCase.Test>`

Gets the tests.

Returns
The test array.

code »getTimeStamp_ ( ) ⇒ `string`

Returns the current time.

Returns
HH:MM:SS.

code »isInsideMultiTestRunner ( ) ⇒ `boolean`

Returns
Whether the test case is running inside the multi test runner.

code »isSuccess ( ) ⇒ `boolean`

Returns
Whether the test was a success.

code »log ( val )

Logs an object to the console, if available.

Parameters
val: `*` The value to log. Will be ToString'd.

code »logError ( name, opt_e ) ⇒ `!goog.testing.TestCase.Error`

Parameters
name: `string` Failed test name. opt_e: `*=` The exception object associated with the failure or a string.
Returns
Error object.

code »maybeFailTestEarly ( testCase ) ⇒ `boolean`

Checks to see if the test should be marked as failed before it is run. If there was an error in setUpPage, we treat that as a failure for all tests and mark them all as having failed.

Parameters
testCase: `goog.testing.TestCase.Test` The current test case.
Returns
Whether the test was marked as failed.

code »next ( ) ⇒ `goog.testing.TestCase.Test`

Returns the current test and increments the pointer.

Returns
The current test case.

code »now ( ) ⇒ `number`

Returns
The current time in milliseconds, don't use goog.now as some tests override it.

code »orderTests_ ( tests )

Reorders the tests depending on the `order` field.

Parameters
tests: `Array.<goog.testing.TestCase.Test>` An array of tests to reorder.

code »pad_ ( number ) ⇒ `string`

Pads a number to make it have a leading zero if it's less than 10.

Parameters
number: `number` The number to pad.
Returns
The resulting string.

code »reset ( )

Resets the test case pointer, so that next returns the first test.

code »saveMessage ( message )

Saves a message to the result set.

Parameters
message: `string` The message to save.

code »setBatchTime ( batchTime )

Parameters
batchTime: `number` Time since the last batch of tests was started.

code »setCompletedCallback ( fn )

Sets the callback function that should be executed when the tests have completed.

Parameters
fn: `Function` The callback function.

code »setTests ( tests )

Sets the tests.

Parameters
tests: `!Array.<goog.testing.TestCase.Test>` A new test array.

code »setUp ( )

Gets called before every goog.testing.TestCase.Test is been executed. Can be overridden to add set up functionality to each test.

code »setUpPage ( )

Gets called before any tests are executed. Can be overridden to set up the environment for the whole test case.

code »shouldRunTests ( ) ⇒ `boolean`

Can be overridden in test classes to indicate whether the tests in a case should be run in that particular situation. For example, this could be used to stop tests running in a particular browser, where browser support for the class under test was absent.

Returns
Whether any of the tests in the case should be run.

code »tearDown ( )

Gets called after every goog.testing.TestCase.Test has been executed. Can be overriden to add tear down functionality to each test.

code »tearDownPage ( )

Gets called after all tests have been executed. Can be overridden to tear down the entire test case.

code »timeout ( fn, time ) ⇒ `number`

Calls a function after a delay, using the protected timeout.

Parameters
fn: `Function` The function to call. time: `number` Delay in milliseconds.
Returns
The timeout id.

code »trimPath_ ( path ) ⇒ `string`

Trims a path to be only that after google3.

Parameters
path: `string` The path to trim.
Returns
The resulting string.

## Instance Properties

### Defined in `goog.testing.AsyncTestCase`

code »activeTest : `(goog.testing.TestCase.Test|undefined)`

The currently active test.

code »cleanedUp_ : `boolean`

Marks if the cleanUp() function has been called for the currently running test.

code »curStepFunc_ : `(Function|undefined)`

The stage of the test we are currently on.

code »curStepName_ : `string`

The name of the stage of the test we are currently on.

code »enableDebugLogs_ : `boolean`

Turn on extra logging to help debug failing async. tests.

code »expectedSignalCount_ : `number`

Number of signals to wait for before continuing testing when waitForSignals is used.

code »inException_ : `boolean`

A flag to prevent recursive exception handling.

code »isReady_ : `boolean`

Flag used to determine if we can move to the next step in the testing loop.

code »nextStepFunc : `(Function|undefined)`

The stage of the test we should run next.

code »nextStepName_ : `string`

The name of the stage of the test we should run next.

code »numControlExceptionsExpected_ : `number`

The number of times we have thrown a ControlBreakingException so that we know not to complain in our window.onerror handler. In Webkit, window.onerror is not supported, and so this counter will keep going up but we won't care about it.

code »origAssert_ : `?`
code »origFail_ : `?`
code »origOnError_ : `(Function|undefined)`

A reference to the original window.onerror function.

code »receivedSignalCount_ : `number`

Number of signals received.

code »returnWillPump_ : `boolean`

Flag that tells us if there is a function in the call stack that will make a call to pump_().

code »stepTimeout : `number`

How long to wait for a single step of a test to complete in milliseconds. A step starts when a call to waitForAsync() is made.

code »timeToSleepAfterFailure : `number`

How long to wait after a failed test before moving onto the next one. The purpose of this is to allow any pending async callbacks from the failing test to finish up and not cause the next test to fail.

code »timeoutHandle_ : `number`

The handle to the current setTimeout timer.

### Defined in `goog.testing.TestCase`

code »batchTime_ : `number`

Time since the last batch of tests was started, if batchTime exceeds `#maxRunTime` a timeout will be used to stop the tests blocking the browser and a new batch will be started.

code »currentTestPointer_ : `number`

Pointer to the current test.

code »exceptionBeforeTest : `*`

Exception object that was detected before a test runs.

code »name_ : `string`

A name for the test case.

code »onCompleteCallback_ : `Function`

Optional callback that will be executed when the test has finalized.

code »order : `string`

The order to run the auto-discovered tests in.

code »result_ : `goog.testing.TestCase.Result`

Object used to encapsulate the test results.

code »running : `boolean`

Whether the test case is running.

code »startTime_ : `number`

Timestamp for when the test was started.

code »started : `boolean`

Whether the test case has ever tried to execute.

code »testsToRun_ : `Object`

Set of test names and/or indices to execute, or null if all tests should be executed. Indices are included to allow automation tools to run a subset of the tests without knowing the exact contents of the test file. Indices should only be used with SORTED ordering. Example valid values:

- [testName]
- [testName1, testName2]
- [2] - will run the 3rd test in the order specified
- [1,3,5]
- [testName1, testName2, 3, 5] - will work

code »tests_ : `!Array`

Array of test functions that can be executed.

## Static Functions

code »goog.testing.AsyncTestCase.createAndInstall ( opt_name ) ⇒ `!goog.testing.AsyncTestCase`

Preferred way of creating an AsyncTestCase. Creates one and initializes it with the G_testRunner.

Parameters
opt_name: `string=` A descriptive name for the test case.
Returns
The created AsyncTestCase.

## Static Properties

code »goog.testing.AsyncTestCase.superClass_ : `goog.testing.TestCase.prototype`