OpenAPI Playwright Generator

Generate comprehensive Playwright test files from OpenAPI specifications with automated boundary value testing.

Features

• Boundary Value Testing: Automatically generates positive and negative test cases
• Parameter Validation: Tests enum values, string constraints, numeric boundaries
• Cross-Parameter Rules: Validates relationships like min/max pairs
• Dynamic Values: Supports runtime value generation (${uniq.email}, @=nowPlusMinutes(30))
• Authentication: Built-in Bearer token support
• Partial Response Validation: Flexible response checking

Complete Setup Guide

Step 1: Create Your Test Project

# Create a new directory for your API tests
mkdir my-api-tests
cd my-api-tests

# Initialize npm project
npm init -y

Step 2: Install Dependencies

# Install the OpenAPI test generator globally
npm install -g openapi-playwright-generator

# Install Playwright for running tests
npm install -D @playwright/test

# Install browser dependencies (required for Playwright)
npx playwright install

Step 3: Create Project Structure

# Create directories for your OpenAPI specs
mkdir specs

# Create Playwright configuration
cat > playwright.config.ts << 'EOF'
import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "generated",
  reporter: ["list", "html"],
  timeout: 60000,
  use: {
    baseURL: process.env.BASE_URL,
    extraHTTPHeaders: {
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    }
  },
  projects: [
    {
      name: "api-tests",
      use: {}
    }
  ]
});
EOF

Step 4: Add Your OpenAPI Specification

# Place your OpenAPI YAML file in the specs directory
# Example: copy your API spec to specs/my-api.yaml

Step 5: Generate and Run Tests

# Generate tests from your OpenAPI spec
openapi-test-gen specs/my-api.yaml --url https://your-api-server.com

# Run tests in headless mode
npx playwright test

# Run tests with interactive UI
npx playwright test --ui

# View test reports
npx playwright show-report

Quick Start (For Existing Projects)

If you already have a Node.js project:

# 1. Install the generator
npm install -g openapi-playwright-generator

# 2. Install Playwright
npm install -D @playwright/test
npx playwright install

# 3. Generate and run tests
openapi-test-gen specs/petstore.yaml --url https://petstore.swagger.io/v2

The tool will:

• ✅ Generate comprehensive test cases
• ✅ Create Playwright test files
• ✅ Automatically run tests if Playwright is available

Installation Options

Global Installation (Recommended)

npm install -g openapi-playwright-generator

Local Installation

npm install openapi-playwright-generator

Usage

Global Command

# Generate tests with base URL
openapi-test-gen specs/petstore.yaml --url https://petstore.swagger.io/v2

# Generate tests (uses URL from spec)
openapi-test-gen specs/openapi.yaml

# Then run the generated tests
npm install -D @playwright/test
npx playwright test --ui

Local Usage

# With npx
npx openapi-playwright-generator specs/petstore.yaml --url https://api.example.com

# Then run the generated tests
npm install -D @playwright/test
npx playwright test --ui

How It Works

1. OpenAPI → Test Plan

Analyzes your OpenAPI spec and generates comprehensive test cases:

• Positive tests: Valid data within constraints
• Negative tests: Invalid data (out of bounds, wrong types)
• Enum validation: Valid and invalid enum values
• Boundary testing: Min/max values, length constraints

2. Test Plan → Playwright Tests

Converts test plans into executable TypeScript test files:

• Path parameter interpolation (/users/{id} → /users/123)
• Query string construction with array support
• Authentication headers injection
• Dynamic value evaluation at runtime

3. Test Execution

Runs generated tests with Playwright:

• Configurable base URL via environment variables
• 60-second timeout per test
• UI mode for interactive debugging

Project Structure

After setup, your project will look like this:

my-api-tests/
├── specs/                    # Your OpenAPI YAML files
│   └── my-api.yaml          # OpenAPI specification
├── testspec/                # Generated test plans (YAML)
│   └── test-plan.http.yaml  # Comprehensive test scenarios
├── generated/               # Generated Playwright test files
│   └── api.http.spec.ts     # TypeScript test code
├── playwright.config.ts     # Playwright configuration
├── package.json            # Project dependencies
└── test-results/           # Test execution reports (created after running)

Generated Test Examples

Input: OpenAPI Parameter

parameters:
  - name: price
    in: query
    schema:
      type: number
      minimum: 0
      maximum: 1000

Generated Test Cases

// Boundary value tests automatically generated:
test("price_min_ok", async ({ request }) => {
  // Tests minimum valid value: price=0
});

test("price_max_ok", async ({ request }) => {
  // Tests maximum valid value: price=1000  
});

test("price_min_bad", async ({ request }) => {
  // Tests below minimum: price=-1 (expects 400)
});

test("price_max_bad", async ({ request }) => {
  // Tests above maximum: price=1001 (expects 400)
});

Configuration & Troubleshooting

Base URL Configuration

# Method 1: Use --url flag (recommended)
openapi-test-gen specs/api.yaml --url https://staging.api.com

# Method 2: Set environment variable
export BASE_URL=https://staging.api.com
openapi-test-gen specs/api.yaml

# Method 3: Use URL from OpenAPI spec (default)
openapi-test-gen specs/api.yaml

Authentication Setup

For APIs requiring authentication, set Bearer tokens via environment variables:

# Set your API token
export TEST_BEARER_TOKEN=your-actual-token-here

# Run tests (token will be included automatically)
openapi-test-gen specs/api.yaml --url https://api.example.com

The generated test plan will include:

auth:
  type: bearer
  tokenEnv: TEST_BEARER_TOKEN

Common Issues & Solutions

Issue: "playwright: command not found"

Solution: Install Playwright in your project directory

npm install -D @playwright/test
npx playwright install

Issue: "Cannot find module" errors

Solution: Ensure you're in the correct directory with package.json

# Make sure you're in your test project directory
pwd  # Should show your project path
ls   # Should show package.json, specs/, etc.

# Re-run the generator
openapi-test-gen specs/your-api.yaml --url https://your-api.com

Issue: Tests fail with network errors

Solution: Verify your API URL and authentication

# Test your API URL manually first
curl -X GET "https://your-api.com/health" -H "Authorization: Bearer $TEST_BEARER_TOKEN"

# Use correct URL in generator
openapi-test-gen specs/api.yaml --url https://your-api.com

Issue: Generated tests don't match your API

Solution: Verify your OpenAPI spec is valid

# Validate your OpenAPI spec online
# Visit: https://editor.swagger.io/
# Or use swagger-codegen: npm install -g swagger-codegen-cli

Example OpenAPI Features Supported

parameters:
  - name: limit
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100
  - name: status
    in: query
    schema:
      type: string
      enum: [active, inactive, pending]

Generates tests for:

• limit=1 (minimum boundary)
• limit=100 (maximum boundary)
• limit=0 (below minimum - negative test)
• limit=101 (above maximum - negative test)
• status=active (valid enum)
• status=invalid (invalid enum - negative test)

Development

Advanced Usage

Environment-Specific Testing

# Development environment
openapi-test-gen specs/api.yaml --url https://dev-api.company.com

# Staging environment  
openapi-test-gen specs/api.yaml --url https://staging-api.company.com

# Production environment (read-only tests)
openapi-test-gen specs/api.yaml --url https://api.company.com

CI/CD Integration

Add to your .github/workflows/api-tests.yml:

name: API Tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: |
          npm install -g openapi-playwright-generator
          npm install -D @playwright/test
          npx playwright install
      
      - name: Generate and run API tests
        env:
          BASE_URL: ${{ secrets.API_BASE_URL }}
          TEST_BEARER_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          openapi-test-gen specs/api.yaml --url $BASE_URL
          npx playwright test

Local Development

git clone <repository>
cd openapi-playwright-generator
npm install

# Test locally
npm run dev specs/example.yaml -- --url https://api.example.com

# Run the generated tests
npm install -D @playwright/test
npx playwright test --ui

Building

npm run build

Requirements

• Node.js >= 16.0.0
• OpenAPI 3.0+ specifications in YAML format

Prerequisites

Before running generated tests, you need to install Playwright:

# Install Playwright as dev dependency
npm install -D @playwright/test

# Install browser dependencies (required for first-time setup)
npx playwright install

# Create basic playwright.config.ts (if needed)
echo 'import { defineConfig } from "@playwright/test";
export default defineConfig({
  testDir: "generated",
  reporter: "list", 
  timeout: 60000,
});' > playwright.config.ts

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request