Async topic

Several utilities are provided for dealing with asynchronous code. The functions are linked below.

These can be useful to wait for an element to appear or disappear in response to an event, user action, timeout, or Future. (See the guide to testing disappearance.)

Read the JS async methods docs for more in-depth discussion and examples

Functions

findAllByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByAltText Queries
Returns a list of ImageElements, InputElements and/or AreaElements with the given text as the value of the alt attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration).
findAllByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByDisplayValue Queries
Returns a list of InputElement, TextAreaElement or SelectElement that has the matching value displayed, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findAllByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, String? selector, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByLabelText Queries
Returns a list of elements that are associated with a LabelElement with the given text, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findAllByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByPlaceholderText Queries
Returns a list of elements with the given text as the value of the placeholder attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration).
findAllByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, bool hidden = false, dynamic name, bool? selected, bool? checked, bool? pressed, bool? expanded, bool queryFallbacks = false, int? level, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByRole Queries
Returns a list of elements with the given role value, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findAllByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByTestId Queries
Returns a list of elements with the given testId value for the data-test-id attribute, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findAllByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, String? selector, dynamic ignore = 'script', Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByText Queries
Returns a list of elements with the given text content, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findAllByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<List<E>> Async ByTitle Queries
Returns a list of elements with the given title as the value of the title attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration).
findByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByAltText Queries
Returns a future with a single ImageElement, InputElement or AreaElement value with the given text as the value of the alt attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration).
findByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByDisplayValue Queries
Returns a future with a single InputElement, TextAreaElement or SelectElement that has the matching value displayed, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, String? selector, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByLabelText Queries
Returns a future with a single element that is associated with a LabelElement with the given text, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByPlaceholderText Queries
Returns a future with a single element value with the given text as the value of the placeholder attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration).
findByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, bool hidden = false, dynamic name, bool? selected, bool? checked, bool? pressed, bool? expanded, bool queryFallbacks = false, int? level, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByRole Queries
Returns a future with a single element value with the given role value, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByTestId Queries
Returns a future with a single element value with the given testId value for the data-test-id attribute, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, String? selector, dynamic ignore = 'script', Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByText Queries
Returns a future with a single element value with the given text content, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).
findByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions?])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<E> Async ByTitle Queries
Returns a future with a single element value with the given title as the value of the title attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration).
waitFor<T>(FutureOr<T> expectation(), {Node? container, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<T> Async
Calls the provided expectation on a given interval and/or when the container DOM changes, completing only if it does not throw, or by throwing if the timeout expires before the expectation succeeds.
waitForElementsToBeRemoved(List<Node> callback(), {Node? container, Duration? timeout, Duration interval = const Duration(milliseconds: 50), QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<void> Async
Waits for the removal of all the elements returned from the callback to be removed from the DOM.
waitForElementToBeRemoved(Node callback(), {Node? container, Duration? timeout, Duration interval = const Duration(milliseconds: 50), QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) → Future<void> Async
Waits for the removal of the single element returned from the callback to be removed from the DOM.