Rocketship Agent Quickstart

Short reference for coding agents (Cursor, Claude Code, Windsurf, etc.) to write and run Rocketship tests.

What is Rocketship?

Rocketship is a testing framework for browser and API testing. A Rocketship test suite is a YAML file (typically kept in a .rocketship directory) made up of one or more tests. Each test has steps, and each step calls a plugin (http, supabase, playwright, agent, etc.).

You can run a single file with -f or an entire .rocketship directory with -d. Use -a to automatically start and stop the local server.

Installation

# macOS
brew tap rocketship-ai/tap && brew install rocketship

# Linux/macOS (portable)
curl -fsSL https://raw.githubusercontent.com/rocketship-ai/rocketship/main/scripts/install.sh | bash

# ----- PREREQS -----
# required for local runs
brew install temporal
# required for browser testing
pip install playwright
playwright install chromium
# required for agent plugin steps
pip install claude-agent-sdk

Things to ALWAYS Remember. THEY ARE BIBLE.

• Rocketship YAML files are strongly typed and must be 100% accurate in order to run. NEVER make assumptions on ANY yaml schema, eg. plugin configs. ALWAYS fetch the docs and read them before editing.

Basic Test Structure

name: "Test Suite Name"
tests:
  - name: "Test Case Name"
    steps:
      - name: "Step Name"
        plugin: "http"
        config:
          method: "GET"
          url: "https://api.example.com/endpoint"
        assertions:
          - type: "status_code"
            expected: 200
        save:
          - json_path: ".id"
            as: "resource_id"

Running Tests

rocketship run -af test.yaml      # Run a test file with auto start/stop of local server
rocketship run -ad .rocketship    # starts the local engine, runs the tests, shuts the engine down

The -a flag is an extremely important flag to use if you're running tests locally (not connecting to the remote cloud). It will automatically start and stop the local server for you after the tests run, so you don't have to manually start and stop the server. If you really wanted to start and stop the server manually, do:

rocketship start server -b # starts the local server in the background
rocketship run test.yaml # runs the tests against the local server
rocketship stop server # stops the local server

I highly recommend you just use the -a flag and let Rocketship handle the server for you.

Variables

# Built-in
{{ .run.id }}  # Unique test run ID

# Environment (from .env file or system env variables)
{{ .env.API_KEY }}
{{ .env.DATABASE_URL }}

# Config (from vars section in YAML or var file)
{{ .vars.base_url }}
{{ .vars.timeout }}

# Runtime (saved during execution)
{{ user_id }}  # From previous save

Passing Variables and Environment

Environment variables:

1. System: export API_KEY=abc && rocketship run -af test.yaml
2. .env file: rocketship run -af test.yaml --env-file .env
3. Custom .env path: rocketship run -af test.yaml --env-file config/.env.staging

Config variables:

1. In YAML: vars: { base_url: "https://api.example.com" }
2. Override via CLI: rocketship run -af test.yaml --var base_url=https://staging.api.example.com
3. From var file: rocketship run -af test.yaml --var-file vars.yaml

Precedence:

• Environment: System env > --env-file
• Config: --var CLI flags > --var-file > YAML vars

Core Plugins (Quick Examples)

Examples below are minimal; ALWAYS verify full schema and types in the plugin docs.

HTTP Plugin

- plugin: http
  config:
    method: "POST"
    url: "{{ .vars.api_url }}/users"
    headers:
      Authorization: "Bearer {{ .env.API_TOKEN }}"
    body: |
      {
        "email": "test-{{ .run.id }}@example.com",
        "name": "Test User"
      }
  assertions:
    - type: "status_code"
      expected: 201
  save:
    - json_path: ".id"
      as: "user_id"

Log Plugin

- plugin: log
  config:
    message: "Starting auth flow for run {{ .run.id }}"

Delay Plugin

- plugin: delay
  config:
    duration: "1s"

Script Plugin

- plugin: script
  config:
    language: javascript
    script: |
      const email = state.user_email || "test@example.com";
      save("normalized_email", email.toLowerCase());

Plugin Docs

Plugin	Description	Docs URL
http	HTTP/API testing	https://docs.rocketship.sh/plugins/http/
supabase	Supabase DB/auth/storage	https://docs.rocketship.sh/plugins/supabase/
sql	SQL databases	https://docs.rocketship.sh/plugins/sql/
agent	AI-driven testing with browser tools	https://docs.rocketship.sh/plugins/agent/
playwright	Scripted browser automation	https://docs.rocketship.sh/plugins/playwright/
browser_use	Cheaper AI for browser automation but way less performant than agent	https://docs.rocketship.sh/plugins/browser-use/
script	JS/shell scripting	https://docs.rocketship.sh/plugins/script/
log	Logging within tests	https://docs.rocketship.sh/plugins/log/
delay	Fixed delays between steps	https://docs.rocketship.sh/plugins/delay/

Advanced Features

• Lifecycle Hooks: init, cleanup.always, cleanup.on_failure for setup/teardown. Docs: https://docs.rocketship.sh/features/lifecycle-hooks/
• Retry Policies: retry block on steps for backoff and retries. Docs: https://docs.rocketship.sh/features/retry-policies/
• Variable Passing: Built-in, Environment, Config, and Runtime. Docs: https://docs.rocketship.sh/features/variables/
• Assertions & Save: Multiple assertion types (status_code, json_path, supabase_count, etc.) and save targets (json_path, header, sql_result, etc.). Docs: https://docs.rocketship.sh/yaml-reference/plugin-reference

Reference

• Full docs: https://docs.rocketship.sh
• Plugin reference: https://docs.rocketship.sh/yaml-reference/plugin-reference
• Command reference: https://docs.rocketship.sh/reference/rocketship
• GitHub: https://github.com/rocketship-ai/rocketship