Skip to main content

the

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

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

        Returns MetaQuestionAdapter<Supported_Context_Type, string>