externalabstractModalDialog

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, ModalDialog.acceptNextWithValue, 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

Constructors

• constructor

Methods

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

Constructors

externalconstructor

• new ModalDialog(): ModalDialog

• Returns ModalDialog

Methods

staticexternalisPresent

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

staticexternalacceptNext

• acceptNext(): Interaction

• Produces an interaction that invokes ModalDialog.acceptNext.

  ---

  Returns Interaction

staticexternalacceptNextWithValue

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

• Produces an interaction that invokes ModalDialog.acceptNextWithValue.

  ---

  Parameters

  • externalvalue: Answerable<string | number>

  Returns Interaction

staticexternaldismissNext

• dismissNext(): Interaction

• Produces an interaction that invokes ModalDialog.dismissNext.

  ---

  Returns Interaction

staticexternallastDialogMessage

• lastDialogMessage(): QuestionAdapter<string>

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

  ---

  Returns QuestionAdapter<string>

staticexternallastDialogState

• lastDialogState(): QuestionAdapter<string>

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

  ---

  Returns QuestionAdapter<string>

externalabstractmessage

• 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.

externalabstractisPresent

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

externalstate

• state(): string

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

  ---

  Returns string