Skip to main content

externalthe

Callable

  • Creates a single-line description of an Activity by transforming a template literal, parameterised with primitive data types, complex data structures, or any other answerables, into a QuestionAdapter<string> that can be used with Task.where and Interaction.where methods.

    const dial = (phoneNumber: Answerable<string>) =>
     Task.where(the `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial('(555) 123-4567'),
      // reported as: Alice dials "(555) 123-4567"
    )

    Trimming the output

    Use DescriptionFormattingOptions to trim the descriptions of template parameters. By default, the output is displayed in full.

    import { actorCalled, Task, the } from '@serenity-js/core'

    const dial = (phoneNumber: Answerable<string>) =>
     Task.where(dial({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial('(555) 123-4567'),
      // reported as: Alice dials "(555) 123-...'
    )

    Using with Questions

    When the is parameterised with questions, it retrieves their description by calling Question.describedBy in the context of the Actor performing the Activity.

    import { actorCalled, Question, Task, the } from '@serenity-js/core'

    const phoneNumber = (areaCode: string, centralOfficeCode: string, lineNumber: string) =>
     Question.about('phone number', actor => {
        return `(${ this.areaCode }) ${ this.centralOfficeCode }-${ this.lineNumber }`
      })

    const dial = (phoneNumber: Answerable<string>) =>
     Task.where(dial({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial(phoneNumber('555', '123', '4567'),
      // reported as: Alice dials phone number
    )

    If you'd like the question to be described using its formatted value instead of its description, use Question.formattedValue.

    import { actorCalled, Question, Task, the } from '@serenity-js/core'

    const phoneNumber = (areaCode: string, centralOfficeCode: string, lineNumber: string) =>
      Question.about('phone number', actor => {
        return `(${ this.areaCode }) ${ this.centralOfficeCode }-${ this.lineNumber }`
      }).describedAs(Question.formattedValue())

    const dial = (phoneNumber: Answerable<string>) =>
     Task.where(dial({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial(phoneNumber('555', '123', '4567'),
      // reported as: Alice dials "(555) 123-4567"
    )

    Using with objects with a custom toString method

    When the is parameterised with objects that have a custom toString() method, or answerables resolving to such objects, the toString() method is called to produce the resulting description.

    import { actorCalled, description, Task } from '@serenity-js/core'

    class PhoneNumber {
      constructor(
        private readonly areaCode: string,
        private readonly centralOfficeCode: string,
        private readonly lineNumber: string,
      ) {}

      toString() {
        return `(${ this.areaCode }) ${ this.centralOfficeCode }-${ this.lineNumber }`
      }
    }

    const dial = (phoneNumber: Answerable<PhoneNumber>) =>
     Task.where(description `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial(new PhoneNumber('555', '123', '4567')),
      // reported as: Alice dials (555) 123-4567
    )

    Using with objects without a custom toString method

    When the is parameterised with complex objects that don't have a custom toString() method, or Answerables resolving to such objects, the resulting description will contain a JSON-like string representation of the object.

    import { actorCalled, description, Task } from '@serenity-js/core'

    interface PhoneNumber {
      areaCode: string;
      centralOfficeCode: string;
      lineNumber: string;
    }

    const dial = (phoneNumber: Answerable<PhoneNumber>) =>
     Task.where(the `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial({ areaCode: '555', centralOfficeCode: '123', lineNumber: '4567' }),
      // reported as: Alice dials { areaCode: "555", centralOfficeCode: "123", lineNumber: "4567" }
    )

    Using with masked values

    When the is parameterised with masked values, the resulting description will contain a masked representation of the values.

    import { actorCalled, description, Task } from '@serenity-js/core'

    const dial = (phoneNumber: Answerable<string>) =>
     Task.where(description `#actor dials ${ phoneNumber }`, /* */)

    await actorCalled('Alice').attemptsTo(
      dial(Masked.valueOf('(555) 123-4567')),
      // reported as: Alice dials [a masked value]
    )

    Learn more

    Parameters

    Returns <Supported_Context_Type>(templates: TemplateStringsArray, ...placeholders: (MetaQuestion<Supported_Context_Type, any> | any)[]) => MetaQuestionAdapter<Supported_Context_Type, string>

      • <Supported_Context_Type>(templates: TemplateStringsArray, ...placeholders: (MetaQuestion<Supported_Context_Type, any> | any)[]): MetaQuestionAdapter<Supported_Context_Type, string>

      • Type parameters

        • Supported_Context_Type

        Parameters

        • externaltemplates: TemplateStringsArray
        • externalrest...placeholders: (MetaQuestion<Supported_Context_Type, any> | any)[]

        Returns MetaQuestionAdapter<Supported_Context_Type, string>