@sharpee/transcript-tester

Transcript-based integration testing for Sharpee interactive fiction stories. Write tests that read like gameplay transcripts — player commands paired with assertions on text output, semantic events, and world state.

Quick Start

# Published stories: build and test in one step
npx sharpee build --test

# Sharpee development: use the pre-built bundle (~170ms load)
node dist/cli/sharpee.js --test stories/my-story/tests/transcripts/*.transcript

Example

title: Locked Door
story: my-story
description: Verify the brass key unlocks the cellar door

---

> examine door
[OK: contains "locked"]
[EVENT: true, type="if.event.examined"]

> unlock door with brass key
[OK: contains "unlocked"]
[STATE: true, door.isLocked = false]

> open door
[EVENT: true, type="if.event.opened"]

Features

Text assertions — [OK: contains "..."], [OK: not contains "..."], [OK: matches /regex/]
Event assertions — Verify semantic events by type, position, and data
State assertions — Check entity properties and inventory after commands
Control flow — GOAL/END GOAL, IF/END IF, WHILE/END WHILE, DO/UNTIL, RETRY
Save/restore — Checkpoint world state for walkthrough chaining
Navigation — [NAVIGATE TO: "Room"] auto-pathfinds via BFS
Test commands — $teleport, $take, $kill, $immortal for quick setup

Documentation

For the full guide covering syntax, assertions, directives, CLI flags, and best practices:

Transcript Testing Guide

Architecture decisions:

Package Structure

File	Purpose
`src/parser.ts`	Parses `.transcript` files into structured test data
`src/runner.ts`	Executes transcripts against the game engine
`src/condition-evaluator.ts`	Evaluates condition expressions for directives
`src/navigator.ts`	BFS pathfinding for `NAVIGATE TO`
`src/reporter.ts`	Formats test results for terminal output
`src/cli.ts`	Standalone CLI entry point
`src/fast-cli.ts`	Bundle-optimized CLI (used by `dist/cli/sharpee.js`)
`src/types.ts`	TypeScript type definitions for transcripts, assertions, and directives

API

The package exports its parser and runner for programmatic use:

import { parseTranscript, TranscriptRunner } from '@sharpee/transcript-tester';

const transcript = parseTranscript(fileContents);
const runner = new TranscriptRunner(gameEngine);
const results = await runner.run(transcript);