https://github.com/scenetest/scenetest-js
Scene-based multi-actor E2E testing for modern JS applications
https://github.com/scenetest/scenetest-js
local-first playwright react testing testing-tools typescript-library vite
Last synced: about 7 hours ago
JSON representation
Scene-based multi-actor E2E testing for modern JS applications
- Host: GitHub
- URL: https://github.com/scenetest/scenetest-js
- Owner: scenetest
- License: mit
- Created: 2025-11-29T16:40:14.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-06-22T08:15:37.000Z (15 days ago)
- Last Synced: 2026-06-22T09:13:24.326Z (15 days ago)
- Topics: local-first, playwright, react, testing, testing-tools, typescript-library, vite
- Language: TypeScript
- Homepage: https://scenetest.msnook.xyz
- Size: 3.3 MB
- Stars: 12
- Watchers: 0
- Forks: 0
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
pnpm add @scenetest/checks @scenetest/vite-plugin @scenetest/scenes
```
Framework bindings ship as subpaths of `@scenetest/checks` — import from
`@scenetest/checks/react`, `/vue`, `/solid`, or `/svelte`.
## Quick Start
**1. Add the Vite plugin:**
```typescript
// vite.config.ts
import scenetest from '@scenetest/vite-plugin'
export default defineConfig({
plugins: [react(), scenetest()],
})
```
**2. Write inline assertions in components:**
```tsx
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 ...
}
```
**3. Write scene specs:**
Choose your style — TypeScript or plain markdown:
```typescript
// 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:
```markdown
# user can update their name
user:
- openTo /
- see name-input
- typeInto name-input New Name
- click submit-button
- seeText New Name
```
**4. Run tests:**
```bash
npx scenetest
```
## Documentation
**Guides**
- [Writing Scene Specs](./docs/public/guides/writing-scene-specs.md) — three styles: declarative (ts), text DSL (md), classic driver (ts)
- [Writing Inline Assertions](./docs/public/guides/writing-inline-assertions.md)
- [Building Good Teams of Actors](./docs/public/guides/building-teams.md)
**Reference**
- [Actor API Reference](./docs/public/reference/actor-api.md) — complete method list and selector resolution
- [Writing Tests (Design Reference)](./docs/public/design/writing-tests.md) — both execution models, full DSL reference, macros
**FAQ**
- [Comparing to Playwright](./docs/public/faq/vs-playwright.md)
- [Comparing to Vitest](./docs/public/faq/vs-vitest.md)
- [Comparing to Cypress](./docs/public/faq/vs-cypress.md)
- [Note on Security](./docs/public/faq/security.md)
**Design Docs**
- [TypeScript Scenes & Playwright Specs](./docs/public/reference/concurrent-and-classic.md) — the two TypeScript execution models side-by-side
- [Actors API Design](./docs/public/design/actors-api.md)
- [CLI Design](./docs/public/design/cli-v2.md) — text DSL grammar, selector resolution, warnings
- [Server Actions Design](./docs/public/design/server-actions.md)
- [Reporting System Design](./docs/public/design/dashboard.md)
## 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