name: katalyst-bdd-quickstart description: Getting started with Katalyst BDD (@esimplicity/stack-tests). Covers installation, project setup, first test creation, running tests, and understanding the tag system (@api, @ui, @tui, @hybrid). license: SEE LICENSE IN LICENSE compatibility: opencode metadata: framework: katalyst-bdd audience: developers

Katalyst BDD Quick Start

What This Skill Covers

• Installing @esimplicity/stack-tests and peer dependencies
• Scaffolding a new test project
• Project structure and configuration
• Writing your first feature file
• Running tests
• Understanding the tag system

Installation

Method 1: Scaffold CLI (Recommended)

# From your project root
npx @esimplicity/create-stack-tests

# With a custom directory name
npx @esimplicity/create-stack-tests --dir e2e-tests

# With agent skills pre-installed
npx @esimplicity/create-stack-tests --with-skills --skills-agents opencode

Method 2: Manual Installation

# Install the framework
npm install -D @esimplicity/stack-tests

# Install peer dependencies
npm install -D @playwright/test playwright-bdd typescript

# Optional: TUI testing support
npm install -D tui-tester

Peer Dependencies

Workspace/Local Development

# Using bun workspaces
bun add -d @esimplicity/stack-tests@"file:../packages/stack-tests" @playwright/test playwright-bdd

Project Structure

After scaffolding, your project should look like:

your-project/
├── package.json
├── playwright.config.ts
├── tsconfig.json
├── features/
│   ├── api/
│   │   └── *.feature
│   ├── ui/
│   │   └── *.feature
│   └── steps/
│       ├── fixtures.ts
│       └── steps.ts
└── .env (optional)

Setting Up Fixtures

Create features/steps/fixtures.ts:

import {
  createBddTest,
  PlaywrightApiAdapter,
  PlaywrightUiAdapter,
  UniversalAuthAdapter,
  DefaultCleanupAdapter,
} from '@esimplicity/stack-tests';

export const test = createBddTest({
  createApi: ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
  createUi: ({ page }) => new PlaywrightUiAdapter(page),
  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui }),
  createCleanup: () => new DefaultCleanupAdapter(),
});

Registering Steps

Create features/steps/steps.ts:

import { test } from './fixtures';
import {
  registerApiSteps,
  registerUiSteps,
  registerSharedSteps,
} from '@esimplicity/stack-tests/steps';

// Register built-in steps
registerApiSteps(test);
registerUiSteps(test);
registerSharedSteps(test);

export { test };

Writing Your First Feature File

Create features/api/users.feature:

@api
Feature: User Management API

  Scenario: Create and verify user
    Given I am authenticated as an admin via API
    When I POST "/users" with JSON body:
      """
      { "email": "test@example.com", "name": "Test User" }
      """
    Then the response status should be 201
    And I store the value at "id" as "userId"

    When I GET "/users/{userId}"
    Then the response status should be 200
    And the value at "email" should equal "test@example.com"

Running Tests

# Generate Playwright tests from feature files
npm run gen

# Run all tests
npm test

# Generate step stubs for undefined steps
npm run gen:stubs

Tag System

Tags control which adapters and steps are available:

Apply tags at the Feature or Scenario level:

@api
Feature: API Tests
  # All scenarios inherit @api tag

@ui
Feature: UI Tests
  Scenario: Login flow
    Given I navigate to "/login"
    ...

Custom tags are also supported for filtering:

@api @smoke
Feature: Smoke Tests
  # Can filter with: tags: '@api and @smoke'

Environment Variables

Key environment variables for test configuration:

NPM Scripts (Scaffolded)

Next Steps

• Use the katalyst-bdd-step-reference skill for complete step documentation
• Use the katalyst-bdd-create-test skill for test creation patterns
• Use the katalyst-bdd-architecture skill for custom adapters/ports
• Full docs: https://esimplicityinc.github.io/katalyst-bdd-test/docs/