@angular/cdk/testing

HarnessEnvironment

Class

Base harness environment class that can be extended to allow ComponentHarnesses to be used in different test environments (e.g. testbed, protractor, etc.). This class implements the functionality of both a HarnessLoader and LocatorFactory. This class is generic on the raw element type, E, used by the particular test environment.

API

  
    abstract class HarnessEnvironment<E> implements HarnessLoader ,LocatorFactory {}

constructor

HarnessEnvironment<E>

@paramrawRootElementE

The native root element of this HarnessEnvironment.

@returnsHarnessEnvironment<E>

rootElement

TestElement

The root element of this HarnessEnvironment as a TestElement.

rootElement

TestElement

documentRootLocatorFactory

LocatorFactory

Gets a locator factory rooted at the document root.

@returnsLocatorFactory

locatorFor

() => Promise<LocatorFnResult<T>>

Creates an asynchronous locator function that can be used to find a ComponentHarness instance or element under the root element of this HarnessEnvironment.

For example, given the following DOM and assuming DivHarness.hostSelector is 'div'

<div id="d1"></div><div id="d2"></div>

then we expect:

await lf.locatorFor(DivHarness, 'div')() // Gets a `DivHarness` instance for #d1await lf.locatorFor('div', DivHarness)() // Gets a `TestElement` instance for #d1await lf.locatorFor('span')()            // Throws because the `Promise` rejects

@paramqueriesT

A list of queries specifying which harnesses and elements to search for:

A string searches for elements matching the CSS selector specified by the string.
A ComponentHarness constructor searches for ComponentHarness instances matching the given class.
A HarnessPredicate searches for ComponentHarness instances matching the given predicate.

@returns() => Promise<LocatorFnResult<T>>

locatorForOptional

() => Promise<LocatorFnResult<T> | null>

Creates an asynchronous locator function that can be used to find a ComponentHarness instance or element under the root element of this HarnessEnvironmnet.

For example, given the following DOM and assuming DivHarness.hostSelector is 'div'

<div id="d1"></div><div id="d2"></div>

then we expect:

await lf.locatorForOptional(DivHarness, 'div')() // Gets a `DivHarness` instance for #d1await lf.locatorForOptional('div', DivHarness)() // Gets a `TestElement` instance for #d1await lf.locatorForOptional('span')()            // Gets `null`

@paramqueriesT

A list of queries specifying which harnesses and elements to search for:

A string searches for elements matching the CSS selector specified by the string.
A ComponentHarness constructor searches for ComponentHarness instances matching the given class.
A HarnessPredicate searches for ComponentHarness instances matching the given predicate.

@returns() => Promise<LocatorFnResult<T> | null>

locatorForAll

() => Promise<LocatorFnResult<T>[]>

Creates an asynchronous locator function that can be used to find ComponentHarness instances or elements under the root element of this HarnessEnvironment.

For example, given the following DOM and assuming DivHarness.hostSelector is 'div' and IdIsD1Harness.hostSelector is '#d1'

<div id="d1"></div><div id="d2"></div>

then we expect:

// Gets [DivHarness for #d1, TestElement for #d1, DivHarness for #d2, TestElement for #d2]await lf.locatorForAll(DivHarness, 'div')()// Gets [TestElement for #d1, TestElement for #d2]await lf.locatorForAll('div', '#d1')()// Gets [DivHarness for #d1, IdIsD1Harness for #d1, DivHarness for #d2]await lf.locatorForAll(DivHarness, IdIsD1Harness)()// Gets []await lf.locatorForAll('span')()

@paramqueriesT

A list of queries specifying which harnesses and elements to search for:

A string searches for elements matching the CSS selector specified by the string.
A ComponentHarness constructor searches for ComponentHarness instances matching the given class.
A HarnessPredicate searches for ComponentHarness instances matching the given predicate.

@returns() => Promise<LocatorFnResult<T>[]>

rootHarnessLoader

Promise<HarnessLoader>

@returnsPromise<HarnessLoader>

harnessLoaderFor

Promise<HarnessLoader>

Gets a HarnessLoader instance for an element under the root of this HarnessEnvironment.

@paramselectorstring

The selector for the root element.

@returnsPromise<HarnessLoader>

harnessLoaderForOptional

Promise<HarnessLoader | null>

Gets a HarnessLoader instance for an element under the root of this HarnessEnvironment.

@paramselectorstring

The selector for the root element.

@returnsPromise<HarnessLoader | null>

harnessLoaderForAll

Promise<HarnessLoader[]>

Gets a list of HarnessLoader instances, one for each matching element.

@paramselectorstring

The selector for the root element.

@returnsPromise<HarnessLoader[]>

getHarness

Promise<T>

Searches for an instance of the component corresponding to the given harness type under the HarnessEnvironment's root element, and returns a ComponentHarness for that instance. If multiple matching components are found, a harness for the first one is returned. If no matching component is found, an error is thrown.

@paramqueryHarnessQuery<T>

A query for a harness to create

@returnsPromise<T>

getHarnessOrNull

Promise<T | null>

@paramqueryHarnessQuery<T>

A query for a harness to create

@returnsPromise<T | null>

getAllHarnesses

Promise<T[]>

Searches for all instances of the component corresponding to the given harness type under the HarnessEnvironment's root element, and returns a list ComponentHarness for each instance.

@paramqueryHarnessQuery<T>

A query for a harness to create

@returnsPromise<T[]>

hasHarness

Promise<boolean>

Searches for an instance of the component corresponding to the given harness type under the HarnessEnvironment's root element, and returns a boolean indicating if any were found.

@paramqueryHarnessQuery<T>

A query for a harness to create

@returnsPromise<boolean>

getChildLoader

Promise<HarnessLoader>

Searches for an element with the given selector under the evironment's root element, and returns a HarnessLoader rooted at the matching element. If multiple elements match the selector, the first is used. If no elements match, an error is thrown.

@paramselectorstring

The selector for the root element of the new HarnessLoader

@returnsPromise<HarnessLoader>

getAllChildLoaders

Promise<HarnessLoader[]>

Searches for all elements with the given selector under the environment's root element, and returns an array of HarnessLoaders, one for each matching element, rooted at that element.

@paramselectorstring

The selector for the root element of the new HarnessLoader

@returnsPromise<HarnessLoader[]>

createComponentHarness

T

Creates a ComponentHarness for the given harness type with the given raw host element.

@paramharnessTypeComponentHarnessConstructor<T>

@paramelementE

@returnsT

forceStabilize

Promise<void>

Flushes change detection and async tasks captured in the Angular zone. In most cases it should not be necessary to call this manually. However, there may be some edge cases where it is needed to fully flush animation events. This is an abstrct method that must be implemented by subclasses.

@returnsPromise<void>

waitForTasksOutsideAngular

Promise<void>

Waits for all scheduled or running async tasks to complete. This allows harness authors to wait for async tasks outside of the Angular zone. This is an abstrct method that must be implemented by subclasses.

@returnsPromise<void>

getDocumentRoot

E

Gets the root element for the document.

@returnsE

createTestElement

TestElement

Creates a TestElement from a raw element.

@paramelementE

@returnsTestElement

createEnvironment

HarnessEnvironment<E>

Creates a HarnessEnvironment rooted at the given raw element.

@paramelementE

@returnsHarnessEnvironment<E>

getAllRawElements

Promise<E[]>

Gets a list of all elements matching the given selector under this environment's root element.

@paramselectorstring

@returnsPromise<E[]>