Project Brief — Build a Test Suite Using Only Claude Code

Every lesson in this course has been a contained exercise — generate one test, refactor one file, fix one flake. The capstone integrates all of it into a single project: a complete Playwright TypeScript test suite built from scratch, using Claude Code as your primary tool for every phase from scaffolding to documentation.

The constraint is deliberate. You may use Claude Code to generate all code — but you must review every file it produces before committing. That review requirement is not a formality. It is the skill this project develops.

The target application

Pick one of these publicly available demo applications:

• https://www.saucedemo.com — a simple e-commerce demo with login, product browsing, cart, and checkout. Reliable, predictable, good surface area for a test suite.
• https://demoqa.com — a richer UI with forms, interactions, drag-and-drop, and widgets. More complex, better for stretching selector strategies.
• https://practice.expandtesting.com — a focused practice site with login flows, form validation, and API-backed pages.

Pick the one that interests you most. The choice does not affect the learning goals — what matters is building a real suite against a real application.

Your deliverables

1. Project setup

Use Claude Code to scaffold the entire project:

> Set up a new Playwright TypeScript project in the current directory.
> Configure:
> - Playwright Test with TypeScript
> - Page Object Model (src/pages/)
> - Test directories: tests/smoke/, tests/negative/, tests/visual/
> - Allure HTML reporter
> - GitHub Actions CI workflow that runs on push
> - .gitignore, tsconfig.json, package.json with sensible scripts
> 
> Generate a CLAUDE.md that documents the conventions we'll use.

Review everything Claude Code generates. The folder structure and configuration will shape every file that follows — it is worth 15 minutes of careful reading.

2. At least 15 tests across four categories

• 5 smoke tests — critical happy paths: login, product listing, add to cart, checkout, logout. These should run in under 2 minutes total.
• 5 negative / edge case tests — invalid credentials, empty cart checkout, malformed input, boundary values. Each should assert the specific error message or behaviour, not just that something went wrong.
• 3 visual or layout tests — key pages rendered correctly. Use Playwright's built-in snapshot testing or add visual diffing if you want to go further.
• 2 cross-browser tests — your two most critical smoke tests running on both Chromium and Firefox.

3. Page Objects for at least 5 pages

Generate each POM with the approach from Chapter 2. If Playwright MCP is connected, use live page analysis. If not, use the application's source (right-click → View Page Source in the browser) as context.

For each POM, verify at least three selectors against the real page before committing.

4. Test data fixtures

Generate at least two fixture files or factory classes using the Chapter 2 approach:

• A set of test users (valid credentials, invalid credentials, locked account)
• A set of boundary-value inputs for at least one form field

5. Custom slash commands (minimum three)

Create .claude/commands/ with at least:

• /run-smoke — run the smoke suite and summarise failures
• /generate-test — guided test generation with prompts for feature and scenarios
• One command of your choosing that solves a specific workflow problem you encounter during the project

6. Documentation generated with Claude

Use Claude Code to generate:

• A README.md explaining how to run the tests, the folder structure, and how to add new tests
• A CONTRIBUTING.md with the testing conventions (locator strategy, naming, data patterns)
• Update CLAUDE.md based on what you learned during the build

7. A reflection document

After completing the project, write a one-page REFLECTION.md (you may use Claude Code to help structure it, but the content should be yours):

• What took longer than expected?
• Where did Claude Code's output need the most correction?
• What would you do differently on the next project?
• Time estimate: how long did this take compared to how long it would have taken manually?

Constraints

You may use Claude Code for all code generation. Test files, POMs, config, CI workflows, documentation — all of it.

You must review every Claude-generated file before committing. Apply the review checklist from Chapter 5: stable selectors, meaningful assertions, isolated test data, condition-based waits, proper cleanup.

Document Claude Code failures. In your REFLECTION.md, describe at least three times Claude Code produced something wrong and how you corrected it. These are the most valuable learning moments of the project.

Optional stretch goals

If you finish the core deliverables and want to go further:

• Connect Playwright MCP and use live page analysis for all POM generation — note the quality difference compared to source-based generation
• Add a CI failure analysis workflow from Chapter 5 (failed run → Claude analyses → artefact uploaded)
• Add Playwright's built-in API testing against the application's backend endpoints
• Add performance budget assertions for page load time on the smoke tests

Starting prompt

Once your project directory is ready:

> I'm building a Playwright test suite for [the application you chose].
> 
> First, scaffold the project:
> - npm init playwright@latest equivalent for TypeScript
> - Create the folder structure: src/pages/, tests/smoke/, tests/negative/, 
>   tests/visual/, tests/fixtures/
> - Configure Allure reporting
> - Generate a GitHub Actions workflow at .github/workflows/tests.yml
>   that runs on push to main
> - Generate a CLAUDE.md with the conventions we'll use
> 
> After scaffolding, show me what was created before we write any tests.

Review the scaffold output carefully. The decisions made here — naming conventions, import paths, base configuration — will shape every file that follows.

The next lesson walks through a full implementation phase by phase, with honest reflection on where AI assistance worked well and where it needed human correction.