@storyshots/react

Implements the preview client for react applications:

import { createPreviewApp } from '@storyshots/react';

// Initialize preview
export const { it, describe, each, run } = createPreviewApp({
  // Define default behavior for external dependencies
  createExternals,
  // Mark methods to be logged by default
  createJournalExternals,
});

// Describe stories
const stories = [describe('...', it('...'))];

// Run the preview client
run(stories);

ExternalsFactory

Allows defining default behavior and logging for external dependencies of the application.

---

createExternals

The main factory that initializes external dependencies of the application. Accepts StoryConfig.

createPreviewApp({
  createExternals: () => {
    // This behavior will be used by default in stories
    getUser: async () => DEFAULT_USER;
  },
  /* ... */
});

createJournalExternals

Marks functions in the externals object that should be tracked by default. Once a function is marked as recordable, this action cannot be undone.

Accepts the final externals and StoryConfig.

createPreviewApp({
  createJournalExternals: (externals, config) => ({
    ...externals,
    getUser: config.journal.asRecordable(externals.getUser),
  }),
});

run

In addition to the test factory, returns a run function required to start the preview. Accepts an array of stories.

const { run, it } = createPreview(/* ... */);

run([
  it('works', {
    render: (externals) => <App externals={externals} />, 
  }),
]);

Extensions

@storyshots/react extends the it factory with the following methods:

render

Represents the behavior under test (specifically for react applications, returns the component tree for rendering).

Accepts externals and StoryConfig:

it('...', {
  // Renders the UserProfile component using prepared data from externals.
  render: (externals, config) => <UserProfile externals={externals} />, 
});

previewing

@storyshots/react extends StoryConfig with previewing property that specifies the mode in which the story is running.

• true: The story is running in preview mode.
• false: The story is executed as a test in a background agent.

note

This property is useful for controlling the external environment. For example, animations should be enabled in preview mode (for more intuitive development), but disabled in test execution mode to avoid nondeterministic behavior.

arrange

Prepares external dependencies for a story.

This function is used to set up the environment before running a story.

it('...', {
  arrange: (externals) => ({
    ...externals,
    // Set specific behavior for the method in this story.
    getUser: async () => ({ name: 'John Doe', age: 25 }),
  }),
});

Accepts story configuration as the second argument.

Can also be used to mark methods for logging via Journal:

it('...', {
  arrange: (externals, { journal }) => ({
    ...externals,
    getUser: journal.asRecordable('getUser', externals.getUser),
  }),
});

Can also be used to store temporary state within the story context:

it('...', {
  arrange: (externals) => {
    // count will be preserved in the running story context.
    const count = 0;

    return {
      increment: () => (count += 1),
      get: () => count,
    };
  },
});