@watershed-labs/create

Scaffold a new Watershed test project with a single command.

npx @watershed-labs/create
# or with a positional template arg:
npx @watershed-labs/create otter my-e2e-tests

Each template generates a complete, production-ready testing project — with Cucumber configuration, CLI runner, World subclass, step definitions, utilities, and unit tests.

Templates

| Key | Acronym | Discipline | | ------------ | ------------------------------------------------------------------------------- | -------------------- | | otter | Opinionated Testing Template with E2E Runner | Web / E2E | | dipper | Driven Integration Pattern for Protocol Endpoint Runner | API testing | | vole | Validate Output, Logic & Expectations | Unit & Component | | salamander | Selenium Appium Layer for Android & Mobile Automation | Mobile | | beaver | Benchmark Execution And Volume Endurance Runner | Performance & Load | | pike | Penetration & Intrusion Kit Executor | Security | | egret | Exact Graphical Regression & Element Tracker | Visual Regression | | mussel | Microservice Unit Schema & Service Expectation Layer | Contract Testing | | hatchery | Handled Artificial Test Content Helpers | Test Data & Fixtures |

The animal names are not arbitrary — each reflects the template's personality. See each template's DEFINITION.md and scaffolded README.md for the full backstory.

Usage

npx @watershed-labs/create [template-key] [--name project-name] [--browser chrome] [--headless] [--no-git]

Positional argument

Pass a template key directly to skip the interactive picker:

npx @watershed-labs/create otter my-web-tests
npx @watershed-labs/create dipper my-api-tests
npx @watershed-labs/create beaver my-load-tests

If the key is invalid, the CLI prints available templates and exits with code 1.

Interactive mode

Run without arguments for an interactive prompt:

npx @watershed-labs/create

Select a template from the list, then answer template-specific questions (project name, base URL, browser, threshold, etc.).

Flags

| Flag | Type | Default | Description | | ------------ | ------- | ------- | ------------------------------------------ | | --name | string | prompt | Project directory name | | --browser | string | chrome | Default browser (otter, salamander, egret) | | --headless | boolean | true | Headless mode (otter, salamander, egret) | | --no-git | boolean | false | Skip git init after scaffolding |

How it works

1. The CLI reads the template registry (src/templates/index.js) to list available templates
2. The user picks a template (via positional arg or interactive select)
3. Template-specific prompts are resolved (template.resolveOptions())
4. The generator (src/generator.js) copies template-files/{key}/ to the output directory
5. {{VARS}} are substituted in all .js, .json, .ts, .md, .html, .env, .yml, .yaml, .txt, .feature, .gitignore, .editorconfig, and .template files
6. File paths with {{VARS}} are also renamed
7. .template suffix is stripped (e.g., package.json.template → package.json)
8. Optionally runs git init + initial commit

Template files

Each template lives at template-files/{key}/ and contains:

{key}/
├── cli.js                     # CLI entry point
├── cucumber.js                # Cucumber config delegate
├── runner.js                  # Programmatic Cucumber runner
├── package.json.template      # Dependencies and scripts
├── support/
│   ├── world.js               # World subclass
│   └── hooks.js               # Lifecycle hooks
├── features/
│   └── example.feature        # Sample scenarios
├── step_definitions/
│   └── example.steps.js       # Step implementations
├── utils/
│   ├── constants.js           # Shared constants
│   ├── validation.js          # Config validation
│   ├── EnvConfig.js           # Environment config
│   └── {Error}.js             # Domain error class
├── unit/
│   ├── env-config.test.js     # Env config tests
│   └── validation.test.js     # Validation tests
├── .env.template
├── .gitignore
├── eslint.config.js
├── local.test.config.example.js
├── README.md.template
└── reports/logs/.gitkeep

Templates with browser dependencies (otter, salamander, egret) also include a pages/ directory with BasePage.js and HomePage.js.

Template registry

The registry at src/templates/index.js exports a templates object keyed by template name. Each entry contains:

| Field | Description | | ---------------- | ------------------------------------------ | | key | Unique identifier (matches template-files) | | label | Display name for the CLI picker | | description | One-line summary | | status | 'active' or 'stub' | | resolveOptions | Async function returning {{VAR}} values |

How to add a new template

node scripts/new-template.mjs

Or manually:

1. Create src/templates/{name}.js with key, label, description, resolveOptions
2. Import and register in src/templates/index.js
3. Create template-files/{name}/ with all scaffolded files
4. Add prompts to src/prompts.js as needed
5. Update test/smoke.test.js to verify the new template