Component Testing with Storybook 8+ & Test Runner

+-------------------------------------------------------------------------+
|                  Storybook 8+ CSF3 Story Declaration                    |
|  meta = { component: TransferModal, decorators: [WithThemeProvider] }   |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                            Story: WithPlayFunction                      |
|                                                                         |
|  play: async ({ canvasElement, step }) => {                             |
|    const canvas = within(canvasElement);                                |
|    await step('Enter transfer details', async () => { ... });           |
|    await step('Confirm remittance', async () => { ... });               |
|  }                                                                      |
+-------------------------------------------------------------------------+
                                     |
                   +------------------+------------------+
                   |                                     |
                   v (Interactive UI)                    v (CI Automation)
+------------------------------------+ +----------------------------------+
|      Storybook Browser UI          | |      @storybook/test-runner      |
|  - Interactions Inspector Tab      | |  - Playwright Orchestration      |
|  - Step-by-Step Timeline Debugger  | |  - Headless Chromium / Firefox   |
|  - Visual ARIA Role Indicators     | |  - preVisit / postVisit Hooks    |
+------------------------------------+ +----------------------------------+
                                                         |
                                                         v
                                        +----------------------------------+
                                        |      axe-core a11y Audit Engine  |
                                        |  - WCAG 2.1 AA/AAA Validation    |
                                        |  - Color Contrast & ARIA Audit   |
                                        +----------------------------------+
                                                         |
                                                         v
                                        +----------------------------------+
                                        |      Pass / Fail in CI Console   |
                                        +----------------------------------+

import React, { useState } from 'react';

interface TransferFormProps {
  onSuccess: (amount: number, recipient: string) => void;
  maxDailyLimit?: number;
}

export function TransferForm({ onSuccess, maxDailyLimit = 50_000 }: TransferFormProps) {
  const [recipient, setRecipient] = useState('');
  const [amount, setAmount] = useState('');
  const [error, setError] = useState<string | null>(null);
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    setError(null);

    const parsedAmount = parseFloat(amount);
    if (!recipient.trim()) {
      setError('Recipient account identifier is required');
      return;
    }
    if (isNaN(parsedAmount) || parsedAmount <= 0) {
      setError('Transfer amount must be greater than zero');
      return;
    }
    if (parsedAmount > maxDailyLimit) {
      setError(`Daily limit exceeded: $${maxDailyLimit.toLocaleString()}`);
      return;
    }

    setIsSubmitting(true);
    // Simulate transactional network latency
    await new Promise((resolve) => setTimeout(resolve, 300));
    setIsSubmitting(false);
    onSuccess(parsedAmount, recipient);
  };

  return (
    <form
      onSubmit={handleSubmit}
      aria-label="Money Transfer Form"
      className="p-6 bg-slate-900 border border-slate-800 rounded-xl max-w-md w-full space-y-4"
    >
      <h2 className="text-lg font-bold text-white">Funds Transfer</h2>

      <div>
        <label htmlFor="recipient-input" className="block text-sm font-medium text-slate-300 mb-1">
          Recipient Account Number
        </label>
        <input
          id="recipient-input"
          type="text"
          value={recipient}
          onChange={(e) => setRecipient(e.target.value)}
          placeholder="ACC-489201"
          className="w-full px-3 py-2 bg-slate-800 border border-slate-700 rounded-lg text-white placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-violet-500"
        />
      </div>

      <div>
        <label htmlFor="amount-input" className="block text-sm font-medium text-slate-300 mb-1">
          Transfer Amount ($)
        </label>
        <input
          id="amount-input"
          type="number"
          value={amount}
          onChange={(e) => setAmount(e.target.value)}
          placeholder="5000"
          className="w-full px-3 py-2 bg-slate-800 border border-slate-700 rounded-lg text-white placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-violet-500"
        />
      </div>

      {error && (
        <div role="alert" className="p-3 bg-red-500/10 border border-red-500/30 rounded-lg text-red-400 text-sm">
          {error}
        </div>
      )}

      <button
        type="submit"
        disabled={isSubmitting}
        className="w-full py-2.5 px-4 bg-violet-600 hover:bg-violet-500 disabled:bg-slate-700 text-white font-medium rounded-lg transition-colors cursor-pointer"
      >
        {isSubmitting ? 'Processing...' : 'Confirm Transfer'}
      </button>
    </form>
  );
}

import type { Meta, StoryObj } from '@storybook/react';
import { within, userEvent, expect, fn } from '@storybook/test';
import { TransferForm } from './TransferForm';

const meta: Meta<typeof TransferForm> = {
  title: 'Features/Payments/TransferForm',
  component: TransferForm,
  parameters: {
    layout: 'centered',
  },
  args: {
    onSuccess: fn(),
    maxDailyLimit: 20_000,
  },
};

export default meta;
type Story = StoryObj<typeof TransferForm>;

// Baseline pristine state
export const DefaultState: Story = {};

// Interactive scenario validating successful form completion
export const SuccessfulTransfer: Story = {
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);

    const recipientInput = canvas.getByLabelText('Recipient Account Number');
    const amountInput = canvas.getByLabelText('Transfer Amount ($)');
    const submitButton = canvas.getByRole('button', { name: 'Confirm Transfer' });

    await step('Step 1: Enter valid recipient identifier', async () => {
      await userEvent.type(recipientInput, 'ACC-998877', { delay: 40 });
      await expect(recipientInput).toHaveValue('ACC-998877');
    });

    await step('Step 2: Enter allowable remittance amount', async () => {
      await userEvent.type(amountInput, '12500', { delay: 40 });
      await expect(amountInput).toHaveValue(12500);
    });

    await step('Step 3: Submit transaction and verify callback execution', async () => {
      await userEvent.click(submitButton);

      // Verify completion and inspect argument payload
      await expect(meta.args?.onSuccess).toHaveBeenCalledWith(12500, 'ACC-998877');
    });
  },
};

// Scenario validating daily transaction limit enforcement
export const ExceedsLimitError: Story = {
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);

    const recipientInput = canvas.getByLabelText('Recipient Account Number');
    const amountInput = canvas.getByLabelText('Transfer Amount ($)');
    const submitButton = canvas.getByRole('button', { name: 'Confirm Transfer' });

    await step('Input amount exceeding daily threshold of $20,000', async () => {
      await userEvent.type(recipientInput, 'ACC-112233');
      await userEvent.type(amountInput, '75000');
      await userEvent.click(submitButton);
    });

    await step('Verify validation alert visibility', async () => {
      const alert = await canvas.findByRole('alert');
      await expect(alert).toHaveTextContent('Daily limit exceeded: $20,000');
      await expect(meta.args?.onSuccess).not.toHaveBeenCalled();
    });
  },
};

import type { TestRunnerConfig } from '@storybook/test-runner';
import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';

const config: TestRunnerConfig = {
  // Invoked before story loads in headless browser
  async preVisit(page) {
    // Inject axe-core engine into the page context
    await injectAxe(page);
  },

  // Invoked following play() function execution
  async postVisit(page, context) {
    // Configure strict WCAG 2.1 AA evaluation rules
    await configureAxe(page, {
      rules: [
        // Enforce sufficient text contrast ratios
        { id: 'color-contrast', enabled: true },
        // Enforce explicit accessible labels on interactive buttons
        { id: 'button-name', enabled: true },
        { id: 'aria-valid-attr', enabled: true },
      ],
    });

    // Execute accessibility inspection on the story root container
    await checkA11y(page, '#storybook-root', {
      detailedReport: true,
      detailedReportOptions: {
        html: true,
      },
      axeOptions: {
        runOnly: {
          type: 'tag',
          values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'],
        },
      },
    });
  },
};

export default config;

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build -o storybook-static",
    "test:storybook": "test-runner --url http://localhost:6006",
    "test:storybook:ci": "concurrently -k -s first -n \"SB,TEST\" -c \"magenta,blue\" \"npx http-server storybook-static -p 6006 -s\" \"wait-on tcp:127.0.0.1:6006 && test-runner\""
  }
}

import { render, screen } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';
import { composeStories } from '@storybook/react';
import * as stories from './TransferForm.stories';

// Transform CSF3 story definitions into executable React components
const { SuccessfulTransfer, ExceedsLimitError } = composeStories(stories);

describe('TransferForm integration tests via Portable Stories', () => {
  it('executes play function within in-memory Vitest environment', async () => {
    const onSuccessMock = vi.fn();
    const { container } = render(<SuccessfulTransfer onSuccess={onSuccessMock} />);

    // Execute composed play function within virtual DOM container
    await SuccessfulTransfer.play({ canvasElement: container });

    expect(onSuccessMock).toHaveBeenCalledTimes(1);
    expect(onSuccessMock).toHaveBeenCalledWith(12500, 'ACC-998877');
  });

  it('renders validation error when limit is breached', async () => {
    const { container } = render(<ExceedsLimitError />);
    await ExceedsLimitError.play({ canvasElement: container });

    const alertElement = await screen.findByRole('alert');
    expect(alertElement).toBeInTheDocument();
  });
});