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

• ChainableSetter<Notes>

Index

Constructors

• constructor

Methods

• has
• get
• set
• delete
• clear
• size
• toJSON
• toString

Constructors

externalconstructor

• new NotepadAdapter<Notes>(): NotepadAdapter<Notes>

• Type parameters

  • Notes: Record<any, any>

  Returns NotepadAdapter<Notes>

Methods

externalhas

• has<Subject>(subject: Subject): QuestionAdapter<boolean>

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

  Learn more

  • Notepad.has}

  ---

  Type parameters

  • Subject: string | number | symbol

  Parameters

  • externalsubject: Subject

    A subject (name) that uniquely identifies a given note

  Returns QuestionAdapter<boolean>

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

externalget

• get<Subject>(subject: Subject): QuestionAdapter<Notes[Subject]>

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

  Learn more

  • Notepad.get}

  @throws

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

  ---

  Type parameters

  • Subject: string | number | symbol

  Parameters

  • externalsubject: Subject

    A subject (name) that uniquely identifies a given note

  Returns QuestionAdapter<Notes[Subject]>

  The value of the previously recorded note.

externalset

• set<Subject>(subject: Subject, value: Answerable<Notes[Subject]>): ChainableSetter<Notes> & Interaction

• Implementation of ChainableSetter.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

  • Notepad.set

  ---

  Type parameters

  • Subject: string | number | symbol

  Parameters

  • externalsubject: Subject

    A subject (name) that uniquely identifies a given note

  • externalvalue: Answerable<Notes[Subject]>

    The value to record

  Returns ChainableSetter<Notes> & Interaction

externaldelete

• delete<Subject>(subject: Subject): QuestionAdapter<boolean>

• 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

  • Notepad.delete

  ---

  Type parameters

  • Subject: string | number | symbol

  Parameters

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

externalclear

• clear(): Interaction

• 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

  • Notepad.clear

  ---

  Returns Interaction

externalsize

• size(): QuestionAdapter<number>

• 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

  • Notepad.size

  ---

  Returns QuestionAdapter<number>

externaltoJSON

• toJSON(): QuestionAdapter<JSONObject>

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

externaltoString

• toString(): string

• @inheritDoc

  ---

  Returns string