@computerwwwizards/screenplay-storybook

A lightweight implementation of the Screenplay Pattern (Actor, Ability, Performable, Question) for writing Storybook interaction tests. It wraps storybook/test's userEvent/canvas behind DOM-aware PageElement/By locators and a library of interactions (Click, Enter, Hover, ...) and assertions (Ensure, equals, isVisible, ...), so play functions read as user intent instead of raw DOM calls.

Installation

npm install @computerwwwizards/screenplay-storybook storybook

storybook is a peer dependency — install whichever version of Storybook (^10.5.6) your project already uses.

Examples

Inside a Storybook story's play function:

import {
  Actor,
  BrowseWithStorybook,
  By,
  PageElement,
  Click,
  Enter,
  Ensure,
  Text,
  equals,
} from '@computerwwwizards/screenplay-storybook';

export const play = async ({ canvas, userEvent, canvasElement }) => {
  const actor = Actor.named('Alice').whoCan(
    BrowseWithStorybook.using({ userEvent, canvas, canvasElement })
  );

  const usernameInput = PageElement.located(By.role('textbox'));
  const submitButton = PageElement.located(By.role('button'));
  const result = PageElement.located(By.testId('result'));

  await actor.attemptsTo(
    Enter.theValue('alice').into(usernameInput),
    Click.on(submitButton),
    Ensure.that(Text.of(result), equals('Welcome, alice!'))
  );
};

Actor.attemptsTo(...) runs a sequence of Performables; Ensure.that(question, expectation) resolves a Question (like Text.of(...)) and asserts it against an Expectation (like equals(...), isVisible(), contains(...)). By supports css, id, role, text, labelText, placeholderText, and testId locators, each usable both against a plain DOM container and against Testing-Library-style canvas queries.

Troubleshooting

• Error: Actor <name> does not have the Ability to BrowseWithStorybook — the actor was never given .whoCan(BrowseWithStorybook.using({...})). Every actor that resolves PageElement/PageElements or runs DOM interactions needs this ability.
• Unable to locate element described by ... — the By locator didn't match anything in canvasElement (or via canvas, when provided). Double check the locator against the rendered story markup.
• Wait.upTo(...).until(...) throws Timeout of Nms exceeded — the polled Question/Expectation never became true within the timeout; increase the duration via Wait.upTo(Duration.ofSeconds(n)) or verify the expected state is actually reachable.

Changelog

See CHANGELOG.md (generated by Changesets on release).

Additional resources

• storybook-demo example — a full Storybook project using this package alongside @computerwwwizards/spec-glue

License information

MIT © computerwwwizards