Skip to main content

NotepadAdapter <Notes>

Serenity/JS Screenplay Pattern-style adapter for the Notepad, that makes it easier for the actors to access its APIs.

See TakeNotes, Notepad and notes for more examples.

Implements

Index

Constructors

Methods

Constructors

constructor

Methods

has

  • Checks if a note identified by subject exists in the notepad.

    Learn more

    Type parameters

    • Subject: string | number | symbol

    Parameters

    • subject: Subject

      A subject (name) that uniquely identifies a given note

    Returns QuestionAdapter<boolean>

    Question that resolves to true if the note exists, false otherwise

get

  • Retrieves a note, identified by subject, from the notepad.

    Learn more

    @throws

    Throws a LogicError if the note with a given subject has never been recorded.

    Type parameters

    • Subject: string | number | symbol

    Parameters

    • subject: Subject

      A subject (name) that uniquely identifies a given note

    Returns QuestionAdapter<Notes[Subject]>

    The value of the previously recorded note.

set

  • Resolves a given Answerable<value> and stores it in the notepad, uniquely identified by its subject.

    Pro tip: calls to set can be chained and result in an accumulation of values to be recorded in the Notepad. Those values are resolved and recorded when the Interaction returned by this method is performed by an Actor.

    If a note identified by a given subject is set multiple times, the last call wins.

     import { actorCalled, notes, TakeNotes } from '@serenity-js/core'
     import { Ensure, equals } from '@serenity-js/assertions'

     interface MyNotes {
         stringNote: string;
         numberNote: number;
     }

    await actorCalled('Alice')
      .whoCan(TakeNotes.usingAnEmptyNotepad<MyNotes>());
      .attemptsTo(

        notes<MyNotes>()
          .set('stringNote', 'example')
          .set('numberNote', Promise.resolve(42))
          .set('stringNote', 'another example'),

        Ensure.equal(notes().toJSON(), {
          firstNote: 'another example',
          secondNote: 42,
        })
    )

    Learn more

    Type parameters

    • Subject: string | number | symbol

    Parameters

    • subject: Subject

      A subject (name) that uniquely identifies a given note

    • value: Answerable<Notes[Subject]>

      The value to record

    Returns ChainableSetter<Notes> & Interaction

delete

  • Removes the note identified by subject from the notepad.

    Using as an Interaction

    import { actorCalled, Check, Log, notes } from '@serenity-js/core'
    import { isPresent } from '@serenity-js/assertions'

    interface MyNotes {
      myNote: string;
    }

    await actorCalled('Alice')
      .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
      .attemptsTo(
        notes<MyNotes>().set('myNote', 'example value'),

        notes<MyNotes>().delete('myNote'),

        Check.whether(notes<MyNotes>().get('myNote'), isPresent())
          .andIfSo(
            Log.the('myNote is present'),
          )
          .otherwise(
            Log.the('myNote was deleted'),
          )
      )
      // logs: myNote was deleted

    Using as a Question

    import { actorCalled, Check, Log, notes } from '@serenity-js/core'
    import { isTrue } from '@serenity-js/assertions'

    interface MyNotes {
      myNote: string;
    }

    await actorCalled('Alice')
      .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
      .attemptsTo(
        notes<MyNotes>().set('myNote', 'example value'),

        Check.whether(notes<MyNotes>().delete('myNote'), isTrue())
          .andIfSo(
            Log.the('myNote was deleted'),
          )
          .otherwise(
            Log.the('myNote could not be deleted because it was not set'),
          )
      )
      // logs: myNote was deleted

    Learn more

    Type parameters

    • Subject: string | number | symbol

    Parameters

    • subject: Subject

    Returns QuestionAdapter<boolean>

    When used as a Question, resolves to true if the item in the Notepad object existed and has been removed, false otherwise.

clear

  • Deletes all the notes stored in this notepad.

    import { actorCalled, notes } from '@serenity-js/core'
    import { isTrue } from '@serenity-js/assertions'

    interface MyNotes {
      myNote: string;
    }

    await actorCalled('Alice')
      .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
      .attemptsTo(
        notes<MyNotes>().set('myNote', 'example value'),
        Log.the(notes<MyNotes>().size()),   // emits 1
        notes<MyNotes>().clear(),
        Log.the(notes<MyNotes>().size()),   // emits 0
      )

    Learn more

    Returns Interaction

size

  • Returns the number of notes stored in the notepad.

    import { actorCalled, notes } from '@serenity-js/core'
    import { isTrue } from '@serenity-js/assertions'

    interface MyNotes {
      myNote: string;
    }

    await actorCalled('Alice')
      .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
      .attemptsTo(
        Log.the(notes<MyNotes>().size()),   // emits 0
        notes<MyNotes>().set('myNote', 'example value'),
        Log.the(notes<MyNotes>().size()),   // emits 1
      )

    Learn more

    Returns QuestionAdapter<number>

toJSON

  • Produces a QuestionAdapter that resolves to a JSONObject representing the resolved notes stored in the notepad.

    Note that serialisation to JSON will simplify some data types that might not be serialisable by default, but are commonly used in data structures representing actor’s notes. For example a Map will be serialised as a regular JSON object, a Set will be serialised as Array.

    Additionally, notepad assumes that the data structure you use it with does not contain cyclic references.

    To learn more about the serialisation mechanism used by the notepad, please refer to TinyTypes documentation.

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

    await actorCalled('Alice')
      .whoCan(TakeNotes.using(Notepad.with({
        aSet: new Set(['apples', 'bananas', 'cucumbers']),
        aPromisedValue: Promise.resolve(42),
        aString: 'example'
      })))
      .attemptsTo(
        Log.the(notes().toJSON()),
      )
      // emits: {
      //    aSet: ['apples', 'bananas', 'cucumbers']
      //    aPromisedValue: 42,
      //    aString: 'example',
      // }

    Returns QuestionAdapter<JSONObject>

toString

  • toString(): string
  • @inheritDoc

    Returns string