START HERE / GETTING STARTED

Your first demo.
Directed by your agent.

Give your agent the Showrunner skill. It handles the scenario, verification, and recording using your application’s existing setup.

START WITH YOUR AGENT

One skill. The whole first take.

From your application repository, install the Showrunner skill and select your agent. The skill lives alongside the library, so its workflow can evolve with the API.

INSTALL THE SKILL

npx skills add smeltery/showrunner --skill showrunner

The skill works with your coding agent. Install it in the application repository where you want to create the demo.

Then ask for the demo.

YOUR AGENT

Use the showrunner skill to demo this change. Reuse this app’s test setup, verify the outcome, record the walkthrough, and tell me what passed and where the recording is saved.

You get a reusable scenario, verification results, and the recording and trace when the run succeeds. Missing access or app setup is reported explicitly.

Read the skill instructions ·Prefer to run it yourself?

MANUAL SETUP

01 / Run the bundled demo

You’ll need Flox. Clone the public repository over HTTPS; no GitHub sign-in is needed. Flox provides Node.js 22 and pnpm. After installation, the bundled scenario runs without a server, account, or network.

TERMINAL

git clone https://github.com/smeltery/showrunner.git
cd showrunner
flox activate
pnpm install
pnpm exec playwright install chromium
pnpm demo
pnpm exec playwright show-report

The demo replaces a draft task, adds it to the release checklist, and asserts that the list contains exactly that task. Playwright saves the video and trace intest-results/.

To watch the browser as it runs, use pnpm demo -- --headed.

02 / Bring it to your application

Install Showrunner alongside @playwright/test. Choose the installation method that matches your access.

From a local build

cd /path/to/showrunner
flox activate
pnpm install
pnpm build
cd /path/to/your/app
pnpm add -D @playwright/test /absolute/path/to/showrunner

From GitHub Packages

Configure the @smeltery scope for GitHub Packages and authenticate with a token that can read this package. Then run pnpm add -D @smeltery/showrunner. Follow thefull installation guidefor registry setup or release tarball installation.

Your application owns authentication, URLs, data setup, and page objects. Showrunner adds the presentation fixture.

03 / Enable recording

Create playwright.demo.config.ts in your application. Put your scenarios indemos/ with the .demo.ts suffix.

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./demos",
  testMatch: "**/*.demo.ts",
  use: {
    baseURL: process.env.DEMO_BASE_URL ?? "http://localhost:3000",
    viewport: { width: 1280, height: 720 },
    video: "on",
    trace: "on",
  },
});

Adapt the example workflow to real routes and accessible names. Start your application, then run:

pnpm exec playwright test --config=playwright.demo.config.ts

Use assertions to verify the outcome. A caption describes the action; it does not prove the action succeeded.

04 / Share the result

Commit the scenario with your change. Share its recording with your pull request using your team’s review workflow. Keep generated media, tokens, and authentication state out of Git.

Planning to use Showrunner in your project? Review the license.

If your first take hits a snag

Package access denied? Verify the registry and token permissions, or use a public release tarball or local build.
Browser missing? Runpnpm exec playwright install chromium. An installed Chrome can also be selected with SHOWRUNNER_BROWSER_CHANNEL=chrome pnpm demo.
Action timed out? Check the locator and the app’s state. Presentation delays are pacing, never readiness checks.