@serenity-js/core
Version:
The core Serenity/JS framework, providing the Screenplay Pattern interfaces, as well as the test reporting and integration infrastructure
201 lines • 5.97 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.Notepad = void 0;
const tiny_types_1 = require("tiny-types");
const errors_1 = require("../../errors");
const io_1 = require("../../io");
const NotepadAdapter_1 = require("./NotepadAdapter");
/**
* Stores notes recorded by an [`Actor`](https://serenity-js.org/api/core/class/Actor/).
*
* See [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/) and [notes](https://serenity-js.org/api/core/function/notes) for more usage examples.
*
* ## Sharing a notepad between actors
*
* ```ts
* import { Actor, Cast, Notepad, TakeNotes } from '@serenity-js/core'
*
* interface MyNotes {
* auth: {
* username: string;
* password: string;
* }
* }
*
* export class Actors implements Cast {
*
* // initialise a shared notepad when the Actors class is initialised
* private readonly sharedNotepad = Notepad.with<MyNotes>({
* auth: {
* username: 'test-user',
* password: 'SuperSecretP@ssword!',
* }
* });
*
* prepare(actor: Actor): Actor {
* switch (actor.name) {
* case 'Alice':
* case 'Bob':
* // Alice and Bob will share their notepad
* return actor.whoCan(TakeNotes.using(this.sharedNotepad));
* default:
* // other actors will get their own notepads
* return actor.whoCan(TakeNotes.using(Notepad.empty<AuthCredentials>()));
* }
* }
* }
* ```
*
* ## Learn more
*
* - [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/)
* - [notes](https://serenity-js.org/api/core/function/notes)
* - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
*
* @group Notes
*/
class Notepad extends tiny_types_1.TinyType {
recordedNotes;
/**
* Instantiates a new empty Notepad.
*/
static empty() {
return new Notepad({});
}
/**
* Instantiates a new Notepad with an initial state.
*
* ```ts
* import { actorCalled, Notepad, notes, TakeNotes } from '@serenity-js/core'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* interface MyNotes {
* personalDetails: {
* firstName: string;
* lastName: string;
* }
* }
*
* actorCalled('Leonard')
* .whoCan(
* TakeNotes.using(
* Notepad.with<MyNotes>({
* personalDetails: {
* firstName: 'Leonard',
* lastName: 'McLaud',
* }
* })
* )
* )
* .attemptsTo(
* Ensure.that(
* notes<MyNotes>().get('personalDetails').firstName,
* equals('Leonard')
* ),
* )
* ```
*
* @param notes
*/
static with(notes) {
return new Notepad(notes);
}
/**
* Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that simplifies access to the notes
* stored in this notepad. Allows the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to record, read, and remove notes.
*
* #### Learn more
* - [notes](https://serenity-js.org/api/core/function/notes)
* - [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/)
* - [`Notepad`](https://serenity-js.org/api/core/class/Notepad/)
*/
static notes() {
return new NotepadAdapter_1.NotepadAdapter();
}
/**
* Instantiates a [`Notepad`](https://serenity-js.org/api/core/class/Notepad/) with an initial state.
*
* @param recordedNotes
* Initial state of the notepad
*/
constructor(recordedNotes) {
super();
this.recordedNotes = recordedNotes;
}
/**
* Checks if a note identified by `subject` exists in the notepad.
*
* @param subject
* A subject (name) that uniquely identifies a given note
*
* @returns
* `true` if the note exists, `false` otherwise
*/
has(subject) {
return Object.prototype.hasOwnProperty.call(this.recordedNotes, subject);
}
/**
* Retrieves a note, identified by `subject`, from the notepad.
*
* @param subject
* A subject (name) that uniquely identifies a given note
*
* @returns
* The value of the previously recorded note.
*
* @throws [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
* Throws a [`LogicError`](https://serenity-js.org/api/core/class/LogicError/) if the note with a given `subject`
* has never been recorded.
*/
get(subject) {
if (!this.has(subject)) {
throw new errors_1.LogicError((0, io_1.d) `Note of ${subject} cannot be retrieved because it's never been recorded`);
}
return this.recordedNotes[subject];
}
/**
* Stores a given `value` uniquely identified by `subject` in the notepad.
*
* @param subject
* A subject (name) that uniquely identifies a given note
*
* @param value
* The value to record.
*/
set(subject, value) {
this.recordedNotes[subject] = value;
return this;
}
/**
* Removes the note identified by `subject` from the notepad.
*
* @param subject
*
* @returns
* `true` if the item in the Notepad object existed and has been removed,
* `false` otherwise.
*/
delete(subject) {
if (this.has(subject)) {
return delete this.recordedNotes[subject];
}
return false;
}
/**
* Deletes all the notes stored in this notepad.
*/
clear() {
const keys = Object.keys(this.recordedNotes);
for (const key of keys) {
this.delete(key);
}
}
/**
* Returns the number of notes stored in the notepad.
*/
size() {
return Object.keys(this.recordedNotes).length;
}
}
exports.Notepad = Notepad;
//# sourceMappingURL=Notepad.js.map