API for testing

API reference for Angular CDK testing

import {ContentContainerComponentHarness} from '@angular/cdk/testing';

Base class for component harnesses that all component harness authors should extend. This base component harness provides the basic ability to locate element and sub-component harness. It should be inherited when defining user's own harness.

Properties
Name Description

locatorFactory: LocatorFactory

Methods
documentRootLocatorFactory

Gets a LocatorFactory for the document root element. This factory can be used to create locators for elements that a component creates outside of its own root element. (e.g. by appending to document.body).

Returns
LocatorFactory

async
forceStabilize

Flushes change detection and async tasks 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.

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

locatorFor

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

Parameters

queries

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.

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>>

An asynchronous locator function that searches for and returns a Promise for the first element or harness matching the given search criteria. Matches are ordered first by order in the DOM, and second by order in the queries list. If no matches are found, the Promise rejects. The type that the Promise resolves to is a union of all result types for each query.

e.g. Given the following DOM: <div id="d1" /><div id="d2" />, and assuming DivHarness.hostSelector === 'div':

  • await ch.locatorFor(DivHarness, 'div')() gets a DivHarness instance for #d1
  • await ch.locatorFor('div', DivHarness)() gets a TestElement instance for #d1
  • await ch.locatorFor('span')() throws because the Promise rejects.

locatorForAll

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

Parameters

queries

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.

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>[]>

An asynchronous locator function that searches for and returns a Promise for all elements and harnesses matching the given search criteria. Matches are ordered first by order in the DOM, and second by order in the queries list. If an element matches more than one ComponentHarness class, the locator gets an instance of each for the same element. If an element matches multiple string selectors, only one TestElement instance is returned for that element. The type that the Promise resolves to is an array where each element is the union of all result types for each query.

e.g. Given the following DOM: <div id="d1" /><div id="d2" />, and assuming DivHarness.hostSelector === 'div' and IdIsD1Harness.hostSelector === '#d1':

  • await ch.locatorForAll(DivHarness, 'div')() gets [ DivHarness, // for #d1 TestElement, // for #d1 DivHarness, // for #d2 TestElement // for #d2 ]
  • await ch.locatorForAll('div', '#d1')() gets [ TestElement, // for #d1 TestElement // for #d2 ]
  • await ch.locatorForAll(DivHarness, IdIsD1Harness)() gets [ DivHarness, // for #d1 IdIsD1Harness, // for #d1 DivHarness // for #d2 ]
  • await ch.locatorForAll('span')() gets [].

locatorForOptional

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

Parameters

queries

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.

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T> | null>

An asynchronous locator function that searches for and returns a Promise for the first element or harness matching the given search criteria. Matches are ordered first by order in the DOM, and second by order in the queries list. If no matches are found, the Promise is resolved with null. The type that the Promise resolves to is a union of all result types for each query or null.

e.g. Given the following DOM: <div id="d1" /><div id="d2" />, and assuming DivHarness.hostSelector === 'div':

  • await ch.locatorForOptional(DivHarness, 'div')() gets a DivHarness instance for #d1
  • await ch.locatorForOptional('div', DivHarness)() gets a TestElement instance for #d1
  • await ch.locatorForOptional('span')() gets null.

async
waitForTasksOutsideAngular

Waits for all scheduled or running async tasks to complete. This allows harness authors to wait for async tasks outside of the Angular zone.

Base class for component harnesses that authors should extend if they anticipate that consumers of the harness may want to access other harnesses within the <ng-content> of the component.

Methods
async
getAllChildLoaders
Parameters

selector

S

Returns
Promise<HarnessLoader[]>

async
getAllHarnesses
Parameters

query

HarnessQuery<T>

Returns
Promise<T[]>

async
getChildLoader
Parameters

selector

S

Returns
Promise<HarnessLoader>

async
getHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<T>

async
getHarnessOrNull
Parameters

query

HarnessQuery<T>

Returns
Promise<T | null>

async
getRootHarnessLoader

Gets the root harness loader from which to start searching for content contained by this harness.

Returns
Promise<HarnessLoader>

async
hasHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<boolean>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

A class used to associate a ComponentHarness class with predicates functions that can be used to filter instances of the class.

Properties
Name Description

harnessType: ComponentHarnessConstructor<T>

Methods
add

Adds a predicate function to be run against candidate harnesses.

Parameters

description

string

A description of this predicate that may be used in error messages.

predicate

AsyncPredicate<T>

An async predicate function.

addOption

Adds a predicate function that depends on an option value to be run against candidate harnesses. If the option value is undefined, the predicate will be ignored.

Parameters

name

string

The name of the option (may be used in error messages).

option

O

The option value.

predicate

AsyncOptionPredicate<T, O>

The predicate function to run if the option value is not undefined.

async
evaluate

Evaluates whether the given harness satisfies this predicate.

Parameters

harness

T

The harness to check

Returns
Promise<boolean>

A promise that resolves to true if the harness satisfies this predicate, and resolves to false otherwise.

async
filter

Filters a list of harnesses on this predicate.

Parameters

harnesses

T[]

The list of harnesses to filter.

Returns
Promise<T[]>

A list of harnesses that satisfy this predicate.

getDescription

Gets a description of this predicate for use in error messages.

getSelector

Gets the selector used to find candidate elements.

static
async
stringMatches

Checks if the specified nullable string value matches the given pattern.

Parameters

value

string | Promise<string>

The nullable string value to check, or a Promise resolving to the nullable string value.

pattern

string | RegExp

The pattern the value is expected to match. If pattern is a string, value is expected to match exactly. If pattern is a regex, a partial match is allowed. If pattern is null, the value is expected to be null.

Returns
Promise<boolean>

Whether the value matches the pattern.

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.

Properties
Name Description

rawRootElement: E

rootElement: TestElement

Methods
createComponentHarness

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

Parameters

harnessType

ComponentHarnessConstructor<T>

element

E

Returns
T

createEnvironment

Creates a HarnessLoader rooted at the given raw element.

Parameters

element

E

Returns
HarnessEnvironment<E>

createTestElement

Creates a TestElement from a raw element.

Parameters

element

E

Returns
TestElement

documentRootLocatorFactory
Returns
LocatorFactory

async
forceStabilize
Returns
Promise<void>

Promise that resolves when the action completes.

async
getAllChildLoaders
Parameters

selector

string

Returns
Promise<HarnessLoader[]>

async
getAllHarnesses
Parameters

query

HarnessQuery<T>

Returns
Promise<T[]>

async
getAllRawElements

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

Parameters

selector

string

Returns
Promise<E[]>

async
getChildLoader
Parameters

selector

string

Returns
Promise<HarnessLoader>

getDocumentRoot

Gets the root element for the document.

Returns
E

async
getHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<T>

async
getHarnessOrNull
Parameters

query

HarnessQuery<T>

Returns
Promise<T | null>

async
harnessLoaderFor
Parameters

selector

string

Returns
Promise<HarnessLoader>

async
harnessLoaderForAll
Parameters

selector

string

Returns
Promise<HarnessLoader[]>

async
harnessLoaderForOptional
Parameters

selector

string

Returns
Promise<HarnessLoader | null>

async
hasHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<boolean>

locatorFor
Parameters

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>>

locatorForAll
Parameters

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>[]>

locatorForOptional
Parameters

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T> | null>

async
rootHarnessLoader
Returns
Promise<HarnessLoader>

async
waitForTasksOutsideAngular
Returns
Promise<void>

Promise that resolves when the action completes.

Interface used to load ComponentHarness objects. This interface is used by test authors to instantiate ComponentHarnesses.

Methods
async
getAllChildLoaders

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

Parameters

selector

string

The selector for the root element of the new HarnessLoader

Returns
Promise<HarnessLoader[]>

A list of HarnessLoaders, one for each matching element, rooted at that element.

async
getAllHarnesses

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

Parameters

query

HarnessQuery<T>

A query for a harness to create

Returns
Promise<T[]>

A list instances of the given harness type.

async
getChildLoader

Searches for an element with the given selector under the current instances'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.

Parameters

selector

string

The selector for the root element of the new HarnessLoader

Returns
Promise<HarnessLoader>

A HarnessLoader rooted at the element matching the given selector.

async
getHarness

Searches for an instance of the component corresponding to the given harness type under the HarnessLoader'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.

Parameters

query

HarnessQuery<T>

A query for a harness to create

Returns
Promise<T>

An instance of the given harness type

async
getHarnessOrNull

Searches for an instance of the component corresponding to the given harness type under the HarnessLoader'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, null is returned.

Parameters

query

HarnessQuery<T>

A query for a harness to create

Returns
Promise<T | null>

An instance of the given harness type (or null if not found).

async
hasHarness

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

Parameters

query

HarnessQuery<T>

A query for a harness to create

Returns
Promise<boolean>

A boolean indicating if an instance was found.

Interface used to create asynchronous locator functions used find elements and component harnesses. This interface is used by ComponentHarness authors to create locator functions for their ComponentHarness subclass.

Properties
Name Description

rootElement: TestElement

The root element of this LocatorFactory as a TestElement.

Methods
documentRootLocatorFactory

Gets a locator factory rooted at the document root.

Returns
LocatorFactory

async
forceStabilize

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.

Returns
Promise<void>

Promise that resolves when the action completes.

async
harnessLoaderFor

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

Parameters

selector

string

The selector for the root element.

Returns
Promise<HarnessLoader>

A HarnessLoader rooted at the first element matching the given selector.

async
harnessLoaderForAll

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

Parameters

selector

string

The selector for the root element.

Returns
Promise<HarnessLoader[]>

A list of HarnessLoader, one rooted at each element matching the given selector.

async
harnessLoaderForOptional

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

Parameters

selector

string

The selector for the root element.

Returns
Promise<HarnessLoader | null>

A HarnessLoader rooted at the first element matching the given selector, or null if no matching element is found.

locatorFor

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

Parameters

queries

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.

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>>

An asynchronous locator function that searches for and returns a Promise for the first element or harness matching the given search criteria. Matches are ordered first by order in the DOM, and second by order in the queries list. If no matches are found, the Promise rejects. The type that the Promise resolves to is a union of all result types for each query.

e.g. Given the following DOM: <div id="d1" /><div id="d2" />, and assuming DivHarness.hostSelector === 'div':

  • await lf.locatorFor(DivHarness, 'div')() gets a DivHarness instance for #d1
  • await lf.locatorFor('div', DivHarness)() gets a TestElement instance for #d1
  • await lf.locatorFor('span')() throws because the Promise rejects.

locatorForAll

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

Parameters

queries

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.

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>[]>

An asynchronous locator function that searches for and returns a Promise for all elements and harnesses matching the given search criteria. Matches are ordered first by order in the DOM, and second by order in the queries list. If an element matches more than one ComponentHarness class, the locator gets an instance of each for the same element. If an element matches multiple string selectors, only one TestElement instance is returned for that element. The type that the Promise resolves to is an array where each element is the union of all result types for each query.

e.g. Given the following DOM: <div id="d1" /><div id="d2" />, and assuming DivHarness.hostSelector === 'div' and IdIsD1Harness.hostSelector === '#d1':

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

locatorForOptional

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

Parameters

queries

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.

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T> | null>

An asynchronous locator function that searches for and returns a Promise for the first element or harness matching the given search criteria. Matches are ordered first by order in the DOM, and second by order in the queries list. If no matches are found, the Promise is resolved with null. The type that the Promise resolves to is a union of all result types for each query or null.

e.g. Given the following DOM: <div id="d1" /><div id="d2" />, and assuming DivHarness.hostSelector === 'div':

  • await lf.locatorForOptional(DivHarness, 'div')() gets a DivHarness instance for #d1
  • await lf.locatorForOptional('div', DivHarness)() gets a TestElement instance for #d1
  • await lf.locatorForOptional('span')() gets null.

async
rootHarnessLoader
Returns
Promise<HarnessLoader>

A HarnessLoader rooted at the root element of this LocatorFactory.

async
waitForTasksOutsideAngular

Waits for all scheduled or running async tasks to complete. This allows harness authors to wait for async tasks outside of the Angular zone.

Returns
Promise<void>

Promise that resolves when the action completes.

Constructor for a ComponentHarness subclass.

Properties
Name Description

hostSelector: string

ComponentHarness subclasses must specify a static hostSelector property that is used to find the host element for the corresponding component. This property should match the selector for the Angular component.

Methods
new
Parameters

locatorFactory

LocatorFactory

Returns
T

A set of criteria that can be used to filter a list of ComponentHarness instances.

Properties
Name Description

ancestor: string

Only find instances that are nested under an element with the given selector.

selector: string

Only find instances whose host element matches the given selector.

Modifier keys that may be held while typing.

Properties
Name Description

alt: boolean

control: boolean

meta: boolean

shift: boolean

This acts as a common interface for DOM elements across both unit and e2e tests. It is the interface through which the ComponentHarness interacts with the component's DOM.

Methods
async
blur

Blur the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
clear

Clear the element's input (for input and textarea elements only).

Returns
Promise<void>

Promise that resolves when the action completes.

async
click

Click the element at the default location for the current environment. If you need to guarantee the element is clicked at a specific location, consider using click('center') or click(x, y) instead.

Parameters

modifiers?

ModifierKeys

Returns
Promise<void>

Promise that resolves when the action completes.

async
dispatchEvent

Dispatches an event with a particular name.

Parameters

name

string

Name of the event to be dispatched.

data?

Record<string, EventData>

Returns
Promise<void>

Promise that resolves when the action completes.

async
focus

Focus the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getAttribute

Gets the value for the given attribute from the element.

Parameters

name

string

Returns
Promise<string | null>

async
getCssValue

Get the computed value of the given CSS property for the element.

Parameters

property

string

Returns
Promise<string>

async
getDimensions

Gets the dimensions of the element.

Returns
Promise<ElementDimensions>

async
getProperty

Gets the value of a property of an element.

Parameters

name

string

Returns
Promise<T>

async
hasClass

Checks whether the element has the given class.

Parameters

name

string

Returns
Promise<boolean>

async
hover

Hovers the mouse over the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
isFocused

Checks whether the element is focused.

Returns
Promise<boolean>

async
matchesSelector

Checks whether this element matches the given selector.

Parameters

selector

string

Returns
Promise<boolean>

async
mouseAway

Moves the mouse away from the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
rightClick

Right clicks on the element at the specified coordinates relative to the top-left of it.

Parameters

relativeX

number

Coordinate within the element, along the X-axis at which to click.

relativeY

number

Coordinate within the element, along the Y-axis at which to click.

modifiers?

ModifierKeys

Modifier keys held while clicking

Returns
Promise<void>

Promise that resolves when the action completes.

async
selectOptions

Selects the options at the specified indexes inside of a native select element.

Parameters

...optionIndexes

number[]

Returns
Promise<void>

Promise that resolves when the action completes.

async
sendKeys

Sends the given string to the input as a series of key presses. Also fires input events and attempts to add the string to the Element's value. Note that some environments cannot reproduce native browser behavior for keyboard shortcuts such as Tab, Ctrl + A, etc.

Parameters

...keys

(string | TestKey)[]

Returns
Promise<void>

Promise that resolves when the action completes.

async
setContenteditableValue

Sets the value of a contenteditable element.

Parameters

value

string

Value to be set on the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
setInputValue

Sets the value of a property of an input.

Parameters

value

string

Returns
Promise<void>

Promise that resolves when the action completes.

async
text

Gets the text from the element.

Parameters

options?

TextOptions

Options that affect what text is included.

Returns
Promise<string>

Properties
Name Description

exclude: string

Optional selector for elements to exclude.

Dimensions for element size and its position relative to the viewport.

Properties
Name Description

height: number

left: number

top: number

width: number

Represents the status of auto change detection.

Properties
Name Description

isDisabled: boolean

Whether auto change detection is disabled.

onDetectChangesNow: () => void

An optional callback, if present it indicates that change detection should be run immediately, while handling the status change. The callback should then be called as soon as change detection is done.

handleAutoChangeDetectionStatus

Allows a test HarnessEnvironment to install its own handler for auto change detection status changes.

Parameters

handler

(status: AutoChangeDetectionStatus) => void

The handler for the auto change detection status.

stopHandlingAutoChangeDetectionStatus

Allows a HarnessEnvironment to stop handling auto change detection status changes.

async
manualChangeDetection

Disables the harness system's auto change detection for the duration of the given function.

Parameters

fn

() => Promise<T>

The function to disable auto change detection for.

async
parallel

Resolves the given list of async values in parallel (i.e. via Promise.all) while batching change detection over the entire operation such that change detection occurs exactly once before resolving the values and once after.

Parameters

values

() => Iterable<T | PromiseLike<T>>

A getter for the async values to resolve in parallel with batched change detection.

Returns
Promise<T[]>

The resolved values.

An async function that returns a promise when called.

type AsyncFactoryFn = () => Promise<T>;

An async function that takes an item and returns a boolean promise

type AsyncPredicate = (item: T) => Promise<boolean>;

An async function that takes an item and an option value and returns a boolean promise.

type AsyncOptionPredicate = (item: T, option: O) => Promise<boolean>;

A query for a ComponentHarness, which is expressed as either a ComponentHarnessConstructor or a HarnessPredicate.

type HarnessQuery = ComponentHarnessConstructor<T> | HarnessPredicate<T>;

The result type obtained when searching using a particular list of queries. This type depends on the particular items being queried.

  • If one of the queries is for a ComponentHarnessConstructor<C1>, it means that the result might be a harness of type C1
  • If one of the queries is for a HarnessPredicate<C2>, it means that the result might be a harness of type C2
  • If one of the queries is for a string, it means that the result might be a TestElement.

Since we don't know for sure which query will match, the result type if the union of the types for all possible results.

e.g. The type: LocatorFnResult&lt;[ ComponentHarnessConstructor&lt;MyHarness&gt;, HarnessPredicate&lt;MyOtherHarness&gt;, string ]&gt; is equivalent to: MyHarness | MyOtherHarness | TestElement.

type LocatorFnResult = {
    [I in keyof T]: T[I] extends new (...args: any[]) => infer C ? C : T[I] extends {
        harnessType: new (...args: any[]) => infer C;
    } ? C : T[I] extends string ? TestElement : never;
}[number];

Data that can be attached to a custom event dispatched from a TestElement.

type EventData = string | number | boolean | Function | undefined | null | EventData[] | {
    [key: string]: EventData;
};

API reference for Angular CDK testing-testbed

Import symbols from @angular/cdk/testing/testbed

A HarnessEnvironment implementation for Angular's Testbed.

Properties
Name Description

rootElement: TestElement

Methods
createEnvironment

Creates a HarnessLoader rooted at the given raw element.

Parameters

element

Element

Returns
HarnessEnvironment<Element>

createTestElement

Creates a TestElement from a raw element.

Parameters

element

Element

Returns
TestElement

static
documentRootLoader

Creates a HarnessLoader at the document root. This can be used if harnesses are located outside of a fixture (e.g. overlays appended to the document body).

Parameters

fixture

ComponentFixture<unknown>

options?

TestbedHarnessEnvironmentOptions

Returns
HarnessLoader

documentRootLocatorFactory
Returns
LocatorFactory

async
forceStabilize

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.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getAllChildLoaders
Parameters

selector

string

Returns
Promise<HarnessLoader[]>

async
getAllHarnesses
Parameters

query

HarnessQuery<T>

Returns
Promise<T[]>

async
getAllRawElements

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

Parameters

selector

string

Returns
Promise<Element[]>

async
getChildLoader
Parameters

selector

string

Returns
Promise<HarnessLoader>

getDocumentRoot

Gets the root element for the document.

Returns
Element

async
getHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<T>

async
getHarnessOrNull
Parameters

query

HarnessQuery<T>

Returns
Promise<T | null>

static
getNativeElement

Gets the native DOM element corresponding to the given TestElement.

Parameters

el

TestElement

Returns
Element

static
async
harnessForFixture

Creates an instance of the given harness type, using the fixture's root element as the harness's host element. This method should be used when creating a harness for the root element of a fixture, as components do not have the correct selector when they are created as the root of the fixture.

Parameters

fixture

ComponentFixture<unknown>

harnessType

ComponentHarnessConstructor<T>

options?

TestbedHarnessEnvironmentOptions

Returns
Promise<T>

async
harnessLoaderFor
Parameters

selector

string

Returns
Promise<HarnessLoader>

async
harnessLoaderForAll
Parameters

selector

string

Returns
Promise<HarnessLoader[]>

async
harnessLoaderForOptional
Parameters

selector

string

Returns
Promise<HarnessLoader | null>

async
hasHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<boolean>

static
loader

Creates a HarnessLoader rooted at the given fixture's root element.

Parameters

fixture

ComponentFixture<unknown>

options?

TestbedHarnessEnvironmentOptions

Returns
HarnessLoader

locatorFor
Parameters

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>>

locatorForAll
Parameters

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T>[]>

locatorForOptional
Parameters

...queries

T

Returns
AsyncFactoryFn<LocatorFnResult<T> | null>

async
rootHarnessLoader
Returns
Promise<HarnessLoader>

async
waitForTasksOutsideAngular

Waits for all scheduled or running async tasks to complete. This allows harness authors to wait for async tasks outside of the Angular zone.

Returns
Promise<void>

Promise that resolves when the action completes.

A TestElement implementation for unit tests.

Properties
Name Description

element: Element

Methods
async
blur

Blur the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
clear

Clear the element's input (for input and textarea elements only).

Returns
Promise<void>

Promise that resolves when the action completes.

async
click

Click the element at the default location for the current environment. If you need to guarantee the element is clicked at a specific location, consider using click('center') or click(x, y) instead.

Parameters

modifiers?

ModifierKeys

Returns
Promise<void>

Promise that resolves when the action completes.

async
click

Click the element at the element's center.

Parameters

location

"center"

modifiers?

ModifierKeys

Returns
Promise<void>

Promise that resolves when the action completes.

async
click

Click the element at the specified coordinates relative to the top-left of the element.

Parameters

relativeX

number

Coordinate within the element, along the X-axis at which to click.

relativeY

number

Coordinate within the element, along the Y-axis at which to click.

modifiers?

ModifierKeys

Modifier keys held while clicking

Returns
Promise<void>

Promise that resolves when the action completes.

async
dispatchEvent

Dispatches an event with a particular name.

Parameters

name

string

Name of the event to be dispatched.

data?

Record<string, EventData>

Returns
Promise<void>

Promise that resolves when the action completes.

async
focus

Focus the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getAttribute

Gets the value for the given attribute from the element.

Parameters

name

string

Returns
Promise<string | null>

async
getCssValue

Get the computed value of the given CSS property for the element.

Parameters

property

string

Returns
Promise<string>

async
getDimensions

Gets the dimensions of the element.

Returns
Promise<ElementDimensions>

async
getProperty

Gets the value of a property of an element.

Parameters

name

string

Returns
Promise<T>

async
hasClass

Checks whether the element has the given class.

Parameters

name

string

Returns
Promise<boolean>

async
hover

Hovers the mouse over the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
isFocused

Checks whether the element is focused.

Returns
Promise<boolean>

async
matchesSelector

Checks whether this element matches the given selector.

Parameters

selector

string

Returns
Promise<boolean>

async
mouseAway

Moves the mouse away from the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
rightClick
Parameters

...args

[ModifierKeys?] | ["center", ModifierKeys?] | [number, number, ModifierKeys?]

Returns
Promise<void>

Promise that resolves when the action completes.

async
selectOptions

Selects the options at the specified indexes inside of a native select element.

Parameters

...optionIndexes

number[]

Returns
Promise<void>

Promise that resolves when the action completes.

async
sendKeys

Sends the given string to the input as a series of key presses. Also fires input events and attempts to add the string to the Element's value. Note that this cannot reproduce native browser behavior for keyboard shortcuts such as Tab, Ctrl + A, etc.

Parameters

...keys

(string | TestKey)[]

Returns
Promise<void>

Promise that resolves when the action completes.

async
sendKeys

Sends the given string to the input as a series of key presses. Also fires input events and attempts to add the string to the Element's value.

Parameters

modifiers

ModifierKeys

...keys

(string | TestKey)[]

Returns
Promise<void>

Promise that resolves when the action completes.

async
setContenteditableValue

Sets the value of a contenteditable element.

Parameters

value

string

Value to be set on the element.

Returns
Promise<void>

Promise that resolves when the action completes.

async
setInputValue

Sets the value of a property of an input.

Parameters

value

string

Returns
Promise<void>

Promise that resolves when the action completes.

async
text

Gets the text from the element.

Parameters

options?

TextOptions

Options that affect what text is included.

Returns
Promise<string>

Options to configure the environment.

Properties
Name Description

queryFn: (selector: string, root: Element) => Iterable<Element> | ArrayLike<Element>

The query function used to find DOM elements.

Failed to load document: /docs-content/api-docs/cdk-testing-protractor.html. Error: OK
Azure & Blue theme selected.