Skip to main content

Element

The Element class is a question class in the Screenplay pattern designed for use with the @testla/screenplay library. This class enables actors to inquire about the state of a web element, such as visibility, enabled state, text, or value, using the BrowseTheWeb ability provided by Testla.

Extends​

This class extends the abstract FrameEnabledQuestion<boolean> which extends Question<boolean> class from Core.

Methods​

answeredBy​

public async answeredBy(actor: Actor): Promise<boolean>;
  • Description: Verifies if an element is in the specified state (visible, enabled, has text, or has value).
  • Parameters:
    • actor - The actor answering this question.
  • Returns: Promise<boolean> - Resolves to true for a positive check, false for a negative check.

toBe​

public static get toBe(): Element;
  • Description: Creates a new instance of the Element class for a positive check.
  • Returns: Element - Returns a new Element instance.

notToBe​

public static get notToBe(): Element;
  • Description: Creates a new instance of the Element class for a negative check.
  • Returns: Element - Returns a new Element instance.

toHave​

public static get toHave(): Element;
  • Description: Alias for toBe. Creates a new instance of the Element class for a positive check.
  • Returns: Element - Returns a new Element instance.

notToHave​

public static get notToHave(): Element;
  • Description: Alias for notToBe. Creates a new instance of the Element class for a negative check.
  • Returns: Element - Returns a new Element instance.

visible​

public visible(selector: Selector, options?: SelectorOptions): Element;
  • Description: Verifies if an element is visible.
  • Parameters:
    • selector - The selector.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

enabled​

public enabled(selector: Selector, options?: SelectorOptions): Element;
  • Description: Verifies if an element is enabled.
  • Parameters:
    • selector - The selector.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

checked​

public enabled(selector: Selector, options?: SelectorOptions): Element;
  • Description: Verifies if an element is checked.
  • Parameters:
    • selector - The selector.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

text​

public text(selector: Selector, text: string | RegExp | (string | RegExp)[], options?: SelectorOptions): Element;
  • Description: Verifies if an element has the given text.
  • Parameters:
    • selector - The selector.
    • text - The text to check.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

value​

public value(selector: Selector, value: string | RegExp, options?: SelectorOptions): Element;
  • Description: Verifies if an element has the given value.
  • Parameters:
    • selector - The selector.
    • value - The value to check.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

count​

public count(selector: Selector, desiredCount: number, options?: SelectorOptions): Element;
  • Description: Verifies if an element has a desired count.
  • Parameters:
    • selector - The selector.
    • desiredCount - The desired count.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

minCount​

public minCount(selector: Selector, minimumCount: number, options?: SelectorOptions): Element;
  • Description: Verifies if an element has a minimum count.
  • Parameters:
    • selector - The selector.
    • minimumCount - The minimum count.
    • options - (optional) Advanced selector lookup options.
  • Returns: Element - Returns this Element instance.

Methods inherited from FrameEnabledQuestion​

inFrame​

Introduced in: 1.3.0

A webpage may be associated with multiple Frame objects. Each webpage possesses a primary frame and interactions at the page level such as clicking, are typically performed within this main frame. In addition to the main frame, a webpage can incorporate extra frames using the HTML 'iframe' tag. These supplementary frames can be targeted for interactions occurring within the specific frame. To reach elements in those frames you can use the inFrame() method to find the specified frame selector using the BrowseTheWeb ability. You can also chain frame objects to go down to the inner most iframe using the inFrame() API. Be aware the sequence starts with outer most iframe and goes down to inner most iframe.

public inFrame(frameSelector: FrameSelector): Check;
  • Description: Finds the specified frame selector using the BrowseTheWeb ability.
  • Parameters:
    • frameSelector - The FrameSelector.
  • Returns: Question - Returns the current question.

Usage:

// Find an element in a specific frame
await actor.asks(
    MyQuestion.is.asExpected().inFrame('#myFrame'),
);

// Find an element in nested frames
await actor.asks(
    MyQuestion.is.asExpected()
        .inFrame('[name="frameTop"]')
        .inFrame('[name="frameMiddle"]'),
);

Methods inherited from Core Question​

failAsFalse​

Introduced in core: 0.5.0

In some cases you may want to ask questions to find out about the status of the system under test to make decisions on how to move on with your test. In order to not fail a test but receive information about questions being answered negative you can use failAsFalse on a question which then returns a boolean value instead.

public get failAsFalse(): Question;
  • Description: Returns false instead of failing when exception occurrs.
  • Returns: Question - Returns the current question.

Usage:

// get evaluation result based on valid check
const evaluationResult = await actor.asks(
    MyQuestion.is.asExpected().failAsFalse,
);

// proceed based on answer from above
if (wasLoggedIn === false) {
    // some code to be executed on false case
}

withAbilityAlias​

Introduced in core: 0.3.0

It happens that there is the need to make use of the same ability but with different settings. The solution Testla Screenplay offers is Ability Aliasing. With that multiple instances of an ability can be assigned to a user at the same time. To use an aliased ability in a question you can use the withAbilityAlias method to define the alias to be used during execution.

public withAbilityAlias(alias: string): Question;
  • Description: Defines the ability alias to be used during execution.
  • Parameters:
    • alias - The alias.
  • Returns: Question - Returns the current question.

Usage:

await actor.asks(
    MyQuestion.is.asExpected().withAbilityAlias('myAlias'),
);