ExSpec: Run Gherkin Tests in Real Browsers with Claude Code—No Step Definitions Required

What It Does

ExSpec is an MCP-compatible tool that bridges the gap between AI-written specifications and actual test execution. Instead of writing step definitions, page objects, or CSS selectors, you write plain-text Gherkin specifications (Given/When/Then) and let Claude Code execute them in a real browser.

When you run npx exspec, Claude Code reads your feature files, navigates your application like a human user would, clicks buttons, fills forms, and validates outcomes—all without any traditional test automation code.

Why It Works With Claude Code

This approach leverages Claude Code's ability to understand natural language specifications and translate them into browser interactions. Unlike traditional BDD frameworks like Cucumber or Behat that require manual implementation of every step, ExSpec uses Claude's reasoning to:

1. Interpret intent from your Gherkin scenarios
2. Navigate your UI based on what's actually visible
3. Adapt to changes in your application's design
4. Provide human-like testing that fails when UX is broken enough to confuse a real user

The tool passes your feature files and a configuration file to Claude Code as context, giving the agent everything it needs to test your application.

How To Set It Up

Prerequisites

• Claude Code CLI installed and authenticated
• Node.js (for npx)

Installation & Configuration

npm install -D @mnapoli/exspec

Create a configuration file at features/exspec.md:

URL: http://localhost:3000

## Application
This is an e-commerce app. The user is a store manager.

## Authentication
Use the `test@example.com` / `password` credentials for authentication.

Write Your First Feature

Create features/shopping_cart.feature:

Feature: Shopping cart
  Scenario: Add a product to the cart
    Given I am logged in
    When I navigate to the product catalog
    And I add the first product to my cart
    Then the cart should show 1 item

Run Tests

# Run all feature files
npx exspec

# Run specific files or directories
npx exspec features/auth/login.feature
npx exspec features/auth/

# Filter by scenario name
npx exspec --filter "invalid password"

# Debug with visible browser
npx exspec --headed

Key Commands You'll Use Daily

• npx exspec --fail-fast - Stop at first failure (perfect for CI)
• npx exspec --headed - Run with visible browser for debugging
• npx exspec features/regression/ - Run specific test suites
• Check features/exspec/2026-03-20-1430.md - Detailed results after each run

When This Shines

1. Rapid prototyping - Write specs as acceptance criteria, then immediately verify them
2. Legacy applications - Test systems without writing/maintaining fragile selectors
3. Design validation - If Claude can't figure out your UI, neither can users
4. Multi-language teams - Write specs in 70+ languages (English, French, German, Spanish, etc.)

Limitations To Know

• Requires a running application (localhost or deployed)
• Browser-based execution is slower than unit tests
• Not suitable for testing edge cases requiring precise DOM manipulation
• Results depend on Claude's interpretation of your specifications

Integration With Your Workflow

Add to your CLAUDE.md:

## Testing Strategy
- Write acceptance criteria as Gherkin features in `features/`
- Run `npx exspec` to validate new features work as specified
- Use `--fail-fast` in CI pipelines
- Review detailed results in `features/exspec/` after each run

This follows Claude Code's recent Auto Mode release for workflow automation, providing another tool for developers to delegate testing tasks directly to Claude.