Scenetest

Evaluate your product, not your tests. A Javascript testing framework with inline assertions and scene-based browser orchestration.

Note: Scenetest is currently quite experimental. You're welcome to check it out, but until version 1.0, the API will be breaking every once in a while. We'll include notices of breaking changes in release notes and often include instructions for LLMs to update your scenes/specs, but until we get to 1.0, I'd consider it a working experiment.

---

Installation

pnpm add @scenetest/checks @scenetest/vite-plugin @scenetest/scenes playwright
pnpm exec scenetest install

Scenetest drives the browser through playwright, and declares it as a peer dependency: your project supplies it, so one copy backs both the browser download and the run. scenetest install downloads the browser builds.

Framework bindings ship as subpaths of @scenetest/checks — import from @scenetest/checks/react, /vue, /solid, or /svelte.

Quick Start

1. Add the Vite plugin:

// vite.config.ts
import scenetest from '@scenetest/vite-plugin'

export default defineConfig({
  plugins: [react(), scenetest()],
})

2. Write inline assertions in components:

import { should, failed } from '@scenetest/checks/react'

function ProfileForm({ user }) {
  should('user should be available', user !== undefined)
  if (user?.error) failed('unexpected error state', { error: user.error })
  return <form>...</form>
}

3. Write scene specs:

Choose your style — TypeScript or plain markdown:

// scenes/profile.spec.ts
import { scene } from '@scenetest/scenes'

scene('user can update their name', ({ actor }) => {
  const user = actor('user')

  user.openTo('/')
  user
    .see('name-input')
    .typeInto('name-input', 'New Name')
    .click('submit-button')
  user.seeText('New Name')
})

Or write specs as human-readable markdown — GitHub-renderable and executable:

<!-- scenes/profile.spec.md -->
# user can update their name
user:
- openTo /
- see name-input
- typeInto name-input New Name
- click submit-button
- seeText New Name

4. Run tests:

npx scenetest

Documentation

Guides

• Writing Scene Specs — three styles: declarative (ts), text DSL (md), classic driver (ts)
• Writing Inline Assertions
• Building Good Teams of Actors

Reference

• Actor API Reference — complete method list and selector resolution
• Writing Tests (Design Reference) — both execution models, full DSL reference, macros

FAQ

• Comparing to Playwright
• Comparing to Vitest
• Comparing to Cypress
• Note on Security

Design Docs

• TypeScript Scenes & Playwright Specs — the two TypeScript execution models side-by-side
• Actors API Design
• CLI Design — text DSL grammar, selector resolution, warnings
• Server Actions Design
• Reporting System Design

Packages

Package	Description
@scenetest/vite-plugin	Vite plugin for production stripping and dev panel
@scenetest/scenes	CLI runner for scene specs
@scenetest/checks	Core should(), failed(), serverCheck() functions
@scenetest/checks/react	React subpath with useCheck hook
@scenetest/checks/vue	Vue subpath with watchCheck composable
@scenetest/checks/solid	Solid subpath with createCheck primitive
@scenetest/checks/svelte	Svelte subpath with checkEffect helper

FAQ

Is it safe to run scenetest in production?

Mmmm, the short answer is "No." Scenetest's Vite plugin strips all the server assertions from the production bundle without deploying them to the server, and it doesn't inject the observer or serve the middleware that powers the collector -- and we do have (some) tests in place for this. And server assertions never have a return value anyway so data access is less of a concern.

So the attack surface is pretty small, but a security audit has not been done. Further the data collection doesn't proactively filter out things like personal data and passwords so it is best used on sample or seed data rather than in production systems.

In the future it might be nice to evolve Scenetest into a production tool for event analytics, observalibility, etc., but for now: it only runs on the dev server 😇

License

MIT