# How to Generate API Test Suites from Routes Using the Claude Skills E2E Scaffolder

> Easily generate API test suites from Next.js routes using the Claude Skills E2E Scaffolder. Automate your testing with Playwright and optional Page Objects.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: tutorial
- Published: 2026-03-09

---

**The Claude Skills repository provides an E2E Test Scaffolder that automatically converts Next.js route definitions into executable Playwright test suites, complete with optional Page Object Models and authentication fixtures.**

The **Claude Skills** repository is a curated collection of production-ready automation utilities organized by domain. Its **E2E Test Scaffolder**, located in the engineering-team skill set, solves the challenge of generating API test suites from routes by scanning Next.js applications and emitting complete Playwright test files.

## Core Architecture of the Test Generator

The scaffolder follows a three-layer pipeline implemented in [`engineering-team/senior-qa/scripts/e2e_test_scaffolder.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering-team/senior-qa/scripts/e2e_test_scaffolder.py).

### RouteScanner

The **RouteScanner** class recursively traverses Next.js `app/` or `pages/` directories to identify route patterns. It executes static analysis through methods like `_scan_directory`, `_process_file`, and `_scan_api_directory` to detect static routes, dynamic segments, and API endpoints while extracting feature flags for forms, authentication guards, navigation elements, and modal interactions.

### TestGenerator

The **TestGenerator** class transforms detected route metadata into executable Playwright tests. Its `generate` method constructs navigation verification, title assertions, authentication checks, and interaction-specific test cases based on the flags identified during scanning.

### PageObjectGenerator

When invoked with the `--include-pom` flag, the **PageObjectGenerator** emits typed Page Object Model classes for each route. These classes provide reusable locators and helper methods, written to `e2e/pages/` via the `generate` method.

## Installation and Prerequisites

Before generating tests, install Playwright in your target project.

```bash
npm i -D @playwright/test
npx playwright install

```

The scaffolder requires Python 3 and writes generated files directly to your specified output directory.

## Generating API Test Suites from Routes

Execute the scaffolder against your Next.js application structure.

```bash
python engineering-team/senior-qa/scripts/e2e_test_scaffolder.py src/app/ --output e2e/

```

This command scans `src/app/`, detects all routes, and writes corresponding [`.spec.ts`](https://github.com/alirezarezvani/claude-skills/blob/main/.spec.ts) files to `e2e/` along with auxiliary configuration files.

Optional flags control the generation behavior:

- `--include-pom`: Generates Page Object Model classes in `e2e/pages/`
- `--routes "/login,/dashboard"`: Restricts generation to specific comma-delimited routes
- `-v` or `--verbose`: Outputs detailed scanning progress to stdout
- `--json`: Emits a JSON summary of the generation operation

After generation, execute the tests immediately:

```bash
npx playwright test e2e/

```

## Customizing Test Generation

The scaffolder is designed for extensibility within [`e2e_test_scaffolder.py`](https://github.com/alirezarezvani/claude-skills/blob/main/e2e_test_scaffolder.py).

To recognize new UI patterns, edit the `INTERACTION_PATTERNS` dictionary in the `RouteScanner` class. To inject custom assertions, modify the `_generate_test_cases` method inside `TestGenerator`. Output naming conventions can be overridden by redefining `_get_test_filename` or `_get_pom_filename`.

The tool automatically creates [`playwright.config.ts`](https://github.com/alirezarezvani/claude-skills/blob/main/playwright.config.ts) and [`fixtures/auth.ts`](https://github.com/alirezarezvani/claude-skills/blob/main/fixtures/auth.ts) if they do not exist, ensuring the generated suite runs without manual boilerplate setup.

## Summary

- The **E2E Test Scaffolder** in [`engineering-team/senior-qa/scripts/e2e_test_scaffolder.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering-team/senior-qa/scripts/e2e_test_scaffolder.py) automatically generates Playwright tests from Next.js route definitions.
- **RouteScanner** extracts route metadata and feature flags, while **TestGenerator** and **PageObjectGenerator** produce executable test files and POM classes.
- Command-line flags like `--include-pom` and `--routes` provide granular control over output scope and structure.
- The generator creates necessary Playwright configuration and authentication fixtures automatically if missing.

## Frequently Asked Questions

### What types of routes does the scaffolder detect?

The tool identifies static routes, dynamic route segments (e.g., `[id]`), and API routes within Next.js `app/` or `pages/` directories. It extracts metadata for authentication boundaries, form elements, navigation links, and modal interactions to generate targeted test cases.

### Can I limit generation to specific routes only?

Yes. Use the `--routes` flag followed by a comma-separated list of paths, such as `--routes "/login,/dashboard,/api/users"`. This restricts the scaffolder to processing only the specified routes rather than the entire application tree.

### Does the scaffolder require existing Playwright configuration?

No. If [`playwright.config.ts`](https://github.com/alirezarezvani/claude-skills/blob/main/playwright.config.ts) or authentication fixtures do not exist in the output directory, the scaffolder automatically generates boilerplate versions. This allows immediate test execution via `npx playwright test` without manual configuration.

### How do I add support for custom UI components in the generated tests?

Extend the `INTERACTION_PATTERNS` dictionary in the `RouteScanner` class within [`e2e_test_scaffolder.py`](https://github.com/alirezarezvani/claude-skills/blob/main/e2e_test_scaffolder.py). Adding new pattern definitions enables the scanner to detect additional UI components and triggers the generation of corresponding interaction tests in the output suite.