Skip to main content

abstractModalDialog

Manages interactions with JavaScript modal dialog windows, triggered by window.alert, window.confirm, or window.prompt, and stores their message so that it can be asserted on once the dialog is handled.

Note that in order to make handling modal windows consistent across the various Web integration tools (such as Playwright, Puppeteer, WebdriverIO or Selenium), Serenity/JS works as follows:

  • Serenity/JS dismisses any modal dialogs by default and stores their message so that it can be asserted on.
  • This behaviour can be changed by invoking ModalDialog.acceptNext, or [[ModalDialog.dismissNext before the dialog is triggered, as per the below examples.
  • Serenity/JS also allows you to Wait.until(ModalDialog, isPresent()) so that you can synchronise your tests with modal dialogs that appear after a delay.

Example HTML widget

In the below example widget, clicking on the button results in a confirmation dialog appearing.

<button id="trigger" onclick="trigger()">Trigger Alert</button>
<p id="result"></p>

<script>
  function trigger() {
    document.getElementById("result").innerHTML = (
      function () {
        return confirm('Continue?')
          ? 'accepted'
          : 'dismissed';
      }
    )();
  }
</script>

Modal dialog gets dismissed by default

import { actorCalled } from '@serenity-js/core'
import { By, Click, Text, PageElement, ModalDialog } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'

const Example = {
  trigger: () =>
    PageElement.located(By.id('trigger')).describedAs('the modal dialog trigger'),

  result: () =>
    PageElement.located(By.id('result')).describedAs('result'),
}

await actorCalled('Nick').attemptsTo(
  Click.on(Example.trigger()),

  Ensure.that(ModalDialog.lastDialogState(), equals('dismissed')),

  Ensure.that(Text.of(Example.result()), equals('dismissed')),
)

Changing modal dialog handler

import { actorCalled } from '@serenity-js/core'
import { By, Click, Text, PageElement, ModalDialog } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'

const Example = {
  trigger: () =>
    PageElement.located(By.id('trigger')).describedAs('the modal dialog trigger'),

  result: () =>
    PageElement.located(By.id('result')).describedAs('result'),
}

await actorCalled('Nick').attemptsTo(
  ModalDialog.acceptNext(),
  // or: ModalDialog.acceptNextWithValue('some value'),
  // or: ModalDialog.dismissNext(),

  Click.on(Example.trigger),

  Ensure.that(ModalDialog.lastDialogState(), equals('accepted')),

  Ensure.that(Text.of(Example.result), equals('accepted')),
)

Learn more

Hierarchy

Implements

  • Optional

Index

Constructors

Methods

Constructors

constructor

Methods

staticisPresent

  • isPresent(): Question<Promise<boolean>>

  • Returns a promise that resolves to true when a modal dialog has been handled, so accepted or dismissed. Returns false for dialogs that haven’t been handled yet.

    Useful when a JavaScript modal dialog is generated after a delay, e.g. triggered by setTimeout.

    Example usage

    import { actorCalled, Wait } from '@serenity-js/core'
    import { Ensure, equals, isPresent } from '@serenity-js/assertions'
    import { ModalDialog } from '@serenity-js/web'

    await actorCalled('Nick').attemptsTo(
      ModalDialog.acceptNext(),
      Wait.until(ModalDialog, isPresent()),
      Ensure.that(ModalDialog.lastDialogState(), equals('accepted')),
    )

    Returns Question<Promise<boolean>>

staticacceptNext

  • acceptNext(): Interaction

staticacceptNextWithValue

  • acceptNextWithValue(value: Answerable<string | number>): Interaction

staticdismissNext

  • dismissNext(): Interaction

staticlastDialogMessage

  • lastDialogMessage(): QuestionAdapter<string>

staticlastDialogState

  • lastDialogState(): QuestionAdapter<string>

abstractmessage

  • message(): Promise<string>

  • Returns the message of the last modal dialog handled, or rejects the promise with a LogicError when no modal dialogs have been observed yet.

    Returns Promise<string>

    Message of the last handled dialog, or a Promise rejected with a LogicError when no dialog has been handled yet.

abstractisPresent

  • isPresent(): Promise<boolean>

  • Returns a promise that resolves to true when a modal dialog has been handled, so either accepted or dismissed. Returns false for dialogs that haven’t been handled yet.

    Useful when a JavaScript modal dialog is generated after a delay, e.g. triggered by setTimeout.

    Returns Promise<boolean>

state

  • state(): string

  • Returns accepted or dismissed for dialogs that have been handled, or absent for those that haven’t been handled yet.

    Returns string