Queries

Last updated 4 months ago

Spectator's API includes convenient methods for querying the DOM as part of a test: query, queryAll, queryLast , queryHost and queryHostAll. All query methods are polymorphic and allow you to query using any of the following techniques:

  • String selector - pass a string selector (in the same style as you would when using jQuery or document.querySelector) to query for elements that match that path in the DOM. This method for querying is equivalent to Angular's By.css predicate. Note that native HTML elements will be returned. For example:

    • spectator.query('div > ul.nav li:first-child')returns a single HTMLElement (if present)

    • spectator.queryAll('div > ul.nav li')returns an array of all matching HTMLElements

  • Type - pass a type (such as a component, directive or provider class) to query for instances of that type in the DOM. This is equivalent to Angular's By.directive predicate. You can optionally pass in a second parameter to read a specific injection token from the matching elements' injectors. For example:

    • spectator.query(MyComponent) returns a single instance of MyComponent (if present)

    • spectator.query(MyComponent, {read: SomeService}) returns the instance of SomeService found in the instance of MyComponent that exists in the DOM (if present)

  • DOMSelector - Spectator allows you to query for elements using selectors inspired by dom-testing-library. Use one of the selector factories that Spectator provides to query for native HTML elements by label, by placeholder and more. These selectors make use of dom-testing-library under the hood, so consult that library's documentation for more insight into their behaviour. The available selectors are:

    • byLabel(query, options?) finds elements that are associated with a label element whose text content matches the provided query

    • byPlaceholder(query, options?) finds elements whose placeholder attributes match the provided query

    • byText(query, options?) finds elements whose text contents match the provided query

    • byAltText(query, options?) finds elements whose alt attributes match the provided query

    • byTitle(query, options?) finds elements whose title attributes match the provided query

    • byValue(query, options?) finds elements whose values match the provided query

    • byTestId(query, options?) finds elements whose data-testid attributes match the provided query

    dom-testing-library provides the flexibility to use these selectors with queries that are strings, regular expressions or functions. Options objects are passed into dom-testing-library untouched. For example:

    • spectator.query(byPlaceholder('Please enter your email address')) will return an HTMLElement whose placeholder attribute is 'Please enter your email address' (if one is present)

    • spectator.queryAll(byText(/donuts/i)) will return any HTMLElements in the DOM whose text content contains the word "donuts" (case insensitive)