Passage Shell

A minimal CLI tool for automated testing of HTML-based interactive fiction projects (Twine, ink, ChoiceScript, etc.).

Installation

npm install
npx playwright install chromium

Quick Start

Generate an example actions file:

node cli.js example

Run actions on your HTML file:

node cli.js run your-story.html actions.json

Usage

node cli.js run <html-file> <actions-file> [options]

Options:
  -h, --headless       Run in headless mode (default: true)
  -s, --slow-mo <ms>   Slow down operations (default: 0)
  -o, --output <file>  Save results to JSON file
  -v, --verbose        Show detailed output

Example Commands

# Run with visible browser
node cli.js run story.html actions.json --headless false

# Run slowly to watch actions
node cli.js run story.html actions.json --slow-mo 500 --headless false

# Save results to file
node cli.js run story.html actions.json -o results.json

# Verbose output
node cli.js run story.html actions.json -v

Action Types

Create a JSON file with an array of actions:

[
  {
    "type": "getText",
    "selector": "body",
    "description": "Get page text"
  },
  {
    "type": "click",
    "selector": "text=Start",
    "description": "Click start link"
  },
  {
    "type": "wait",
    "ms": 500,
    "description": "Wait for transition"
  },
  {
    "type": "getLinks",
    "description": "Get all links"
  },
  {
    "type": "screenshot",
    "path": "screenshot.png",
    "description": "Take screenshot"
  }
]

Supported Actions

| Action | Description | Parameters | |--------|-------------|------------| | click | Click an element | selector | | getText | Get text content | selector | | getHTML | Get HTML content | selector | | getLinks | Get all links | - | | type | Type into input | selector, text | | wait | Wait milliseconds | ms | | waitForSelector | Wait for element | selector, timeout? | | screenshot | Take screenshot | path | | hover | Hover over element | selector | | getAttribute | Get attribute value | selector, attribute | | evaluate | Run JavaScript | script | | select | Select dropdown option | selector, value | | check | Check checkbox | selector | | uncheck | Uncheck checkbox | selector | | goBack | Browser back | - | | goForward | Browser forward | - | | reload | Reload page | - |

Selectors

Playwright supports multiple selector types:

• Text: text=Start or "text=Click me"
• CSS: .passage or #story
• XPath: //a[contains(text(), "Next")]
• Data attributes: [data-passage="intro"]

Examples

Testing a Twine Story

[
  {
    "type": "getText",
    "selector": "tw-story",
    "description": "Get initial passage"
  },
  {
    "type": "click",
    "selector": "text=Begin",
    "description": "Start the story"
  },
  {
    "type": "wait",
    "ms": 300
  },
  {
    "type": "getLinks",
    "description": "Get available choices"
  },
  {
    "type": "click",
    "selector": "tw-link >> nth=0",
    "description": "Click first choice"
  }
]

Testing Any HTML Interactive Fiction

[
  {
    "type": "waitForSelector",
    "selector": "#story",
    "description": "Wait for story to load"
  },
  {
    "type": "getText",
    "selector": "#story",
    "description": "Get current text"
  },
  {
    "type": "click",
    "selector": "a.choice",
    "description": "Click a choice link"
  },
  {
    "type": "screenshot",
    "path": "after-choice.png"
  }
]

Output

With --verbose or --output, you get structured results:

[
  {
    "action": "getText",
    "description": "Get page text",
    "result": {
      "text": "Welcome to the story..."
    }
  },
  {
    "action": "click",
    "description": "Click start",
    "result": {
      "clicked": "text=Start"
    }
  }
]

Requirements

• Node.js >= 18
• Playwright (auto-installed with npm install)

License

MIT