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

• Optional

Hierarchy

• ModalDialog
  • AbsentModalDialog
  • AcceptedModalDialog
  • DismissedModalDialog

Implements

• Optional

Index

Methods

• isPresent
• acceptNext
• acceptNextWithValue
• dismissNext
• lastDialogMessage
• lastDialogState
• message
• isPresent
• state

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

• Produces an interaction that invokes ModalDialog.acceptNext.

  ---

  Returns Interaction

staticacceptNextWithValue

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

• Produces an interaction that invokes ModalDialog.acceptNextWithValue.

  ---

  Parameters

  • value: Answerable<string | number>

  Returns Interaction

staticdismissNext

• dismissNext(): Interaction

• Produces an interaction that invokes ModalDialog.dismissNext.

  ---

  Returns Interaction

staticlastDialogMessage

• lastDialogMessage(): QuestionAdapter<string>

• QuestionAdapter that resolves to ModalDialog.message for the current Page.

  ---

  Returns QuestionAdapter<string>

staticlastDialogState

• lastDialogState(): QuestionAdapter<string>

• QuestionAdapter that resolves to ModalDialog.state for the current Page.

  ---

  Returns 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>

• Implementation of Optional.isPresent

  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

Constructors

constructor

• new ModalDialog(): ModalDialog

• Returns ModalDialog