{"id":33314516,"url":"https://github.com/m3au/playwright-bdd-cursor-template","last_synced_at":"2026-05-04T17:36:11.950Z","repository":{"id":322120119,"uuid":"1088266325","full_name":"m3au/playwright-bdd-cursor-template","owner":"m3au","description":"Playwright BDD with @Given/@When on POMs • Cursor rules so AI writes perfect tests • axe + Lighthouse • strict lint \u0026 CI","archived":false,"fork":false,"pushed_at":"2025-11-18T03:05:33.000Z","size":9246,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-18T04:21:42.526Z","etag":null,"topics":["a11y","accessibility","automation-testing","axe-core","bdd","behavior-driven-development","bun","cursor-ai","cursor-composer","cursor-ide","e2e-testing","end-to-end-testing","gherkin","lighthouse","page-object-model","playwright","playwright-bdd","playwright-test","testing-template","typescript"],"latest_commit_sha":null,"homepage":"https://m3au.github.io/playwright-bdd-cursor-template/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m3au.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T16:33:57.000Z","updated_at":"2025-11-18T03:05:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/m3au/playwright-bdd-cursor-template","commit_stats":null,"previous_names":["m3au/tech-challenge","m3au/playwright-pilot","m3au/playwright-bdd-cursor-template"],"tags_count":4,"template":true,"template_full_name":null,"purl":"pkg:github/m3au/playwright-bdd-cursor-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3au%2Fplaywright-bdd-cursor-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3au%2Fplaywright-bdd-cursor-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3au%2Fplaywright-bdd-cursor-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3au%2Fplaywright-bdd-cursor-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m3au","download_url":"https://codeload.github.com/m3au/playwright-bdd-cursor-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3au%2Fplaywright-bdd-cursor-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32618183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","accessibility","automation-testing","axe-core","bdd","behavior-driven-development","bun","cursor-ai","cursor-composer","cursor-ide","e2e-testing","end-to-end-testing","gherkin","lighthouse","page-object-model","playwright","playwright-bdd","playwright-test","testing-template","typescript"],"created_at":"2025-11-19T12:01:17.586Z","updated_at":"2026-05-04T17:36:11.943Z","avatar_url":"https://github.com/m3au.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Playwright BDD Cursor Template \u003c!-- omit from toc --\u003e\n\n**Opinionated, Cursor-optimized Playwright BDD testing framework with built-in accessibility \u0026 performance auditing**\n\n⚠️ **This is NOT an AI/LLM browser agent or autonomous pilot. It is a battle-tested E2E testing template that works amazingly well with Cursor's Composer/Agent.**\n\n[![CI](https://github.com/m3au/playwright-bdd-cursor-template/actions/workflows/ci.yml/badge.svg)](https://github.com/m3au/playwright-bdd-cursor-template/actions/workflows/ci.yml)\n[![Playwright](https://img.shields.io/badge/Playwright-1.56.1-green)](https://playwright.dev/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-1.3.2-black)](https://bun.sh/)\n[![BDD](https://img.shields.io/badge/BDD-Gherkin-green)](https://cucumber.io/docs/gherkin/)\n[![Axe Accessibility](https://img.shields.io/badge/Axe%20Accessibility-4.11.0-blue)](https://github.com/dequelabs/axe-core)\n[![Lighthouse](https://img.shields.io/badge/Lighthouse-13.0.1-blue)](https://developer.chrome.com/docs/lighthouse/)\n[![Cursor Ready](https://img.shields.io/badge/Cursor-Ready-brightgreen)](https://cursor.sh/)\n[![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-enabled-brightgreen)](https://github.com/features/actions)\n[![Coverage](https://img.shields.io/badge/Coverage-81.84%25-green)](tests/unit/)\n[![TypeScript ESLint](https://img.shields.io/badge/TypeScript%20ESLint-8.46.2-blue)](https://typescript-eslint.io/)\n[![SonarJS](https://img.shields.io/badge/SonarJS-3.0.5-orange)](https://github.com/SonarSource/eslint-plugin-sonarjs)\n[![Unicorn](https://img.shields.io/badge/Unicorn-62.0.0-purple)](https://github.com/sindresorhus/eslint-plugin-unicorn)\n[![Prettier](https://img.shields.io/badge/Prettier-code--formatter-pink)](https://prettier.io/)\n[![CSpell](https://img.shields.io/badge/CSpell-9.2.2-purple)](https://cspell.org/)\n[![Markdownlint](https://img.shields.io/badge/Markdownlint-0.18.1-orange)](https://github.com/DavidAnson/markdownlint)\n[![Husky](https://img.shields.io/badge/Husky-9.1.7-green)](https://typicode.github.io/husky/)\n[![lint-staged](https://img.shields.io/badge/lint--staged-16.2.6-yellow)](https://github.com/lint-staged/lint-staged)\n[![EditorConfig](https://img.shields.io/badge/EditorConfig-enabled-blue)](https://editorconfig.org/)\n[![ES Modules](https://img.shields.io/badge/ES%20Modules-enabled-brightgreen)](https://nodejs.org/api/esm.html)\n[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-blue)](https://github.com/dependabot)\n[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-enabled-brightgreen)](https://pages.github.com/)\n[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)\n\n![Cyberpunk animation showing futuristic cityscape](docs/images/cyberpunk.gif)\n\n\u003e **🎬 Demo Video Coming Soon**: Watch Cursor Composer generate tests, see accessibility checks in action, and explore the GitHub Actions workflow with HTML reports. [Record a 20-30 second demo](https://github.com/m3au/playwright-bdd-cursor-template/issues) and we'll feature it here!\n\n## Table of Contents \u003c!-- omit from toc --\u003e\n\n- [Why This Template Exists](#why-this-template-exists)\n- [About](#about)\n  - [Key Features](#key-features)\n- [Test Scenarios](#test-scenarios)\n  - [UITestingPlayground Challenge](#uitestingplayground-challenge)\n  - [Element Identification (5 scenarios)](#element-identification-5-scenarios)\n  - [Timing \\\u0026 Synchronization (7 scenarios)](#timing--synchronization-7-scenarios)\n  - [Interaction Challenges (5 scenarios)](#interaction-challenges-5-scenarios)\n  - [Advanced Challenges (6 scenarios)](#advanced-challenges-6-scenarios)\n  - [AutomationExercise Challenge](#automationexercise-challenge)\n- [Test Reports](#test-reports)\n- [Documentation](#documentation)\n  - [Challenge Documentation](#challenge-documentation)\n  - [Project Documentation](#project-documentation)\n- [Project Structure](#project-structure)\n- [Quick Start](#quick-start)\n- [Architecture \\\u0026 Patterns](#architecture--patterns)\n  - [Challenge-Based Organization](#challenge-based-organization)\n  - [Page Object Model (POM)](#page-object-model-pom)\n  - [World Fixture](#world-fixture)\n  - [BDD with Gherkin](#bdd-with-gherkin)\n- [AI Assistance](#ai-assistance)\n- [Code Quality](#code-quality)\n\n---\n\n## Why This Template Exists\n\nMost Playwright + BDD setups are either outdated, require separate step-definition files, or completely ignore accessibility/performance. This template fixes all of that and is specifically tuned for Cursor so AI can write and maintain your tests with almost zero friction.\n\n**The Problem:**\n\n- Traditional BDD setups require maintaining separate step-definition files\n- Most templates ignore accessibility and performance testing\n- AI assistants struggle with outdated or poorly documented patterns\n- Slow test execution due to Node.js runtime overhead\n\n**The Solution:**\n\n- ✅ Zero separate step-definition files (decorators on POM methods)\n- ✅ Built-in axe-core accessibility in every run\n- ✅ Lighthouse performance audit in CI\n- ✅ Bun runtime → 3–5× faster installs \u0026 test runs\n- ✅ Cursor.rules + MCP config included (Composer understands your project instantly)\n- ✅ Parallel + sharded GitHub Actions out of the box\n- ✅ Beautiful HTML report published to GitHub Pages\n- ✅ Traces, video, screenshots on failure\n\n## About\n\nThis is a **production-ready Playwright BDD testing template** optimized for Cursor IDE's AI assistant. It provides a complete, opinionated setup for writing maintainable end-to-end tests with built-in accessibility and performance auditing.\n\n**What makes this template special:**\n\n- **Cursor-optimized** — Comprehensive `.cursor/rules/` configuration so AI understands your project structure, patterns, and conventions instantly\n- **Zero boilerplate BDD** — Decorators directly on Page Object Model methods eliminate separate step-definition files\n- **Built-in audits** — Axe accessibility, Lighthouse performance, and Artillery load tests run automatically in CI\n- **Bun-powered** — 3–5× faster than Node.js for installs and test execution\n- **Production-ready CI/CD** — Parallel sharded tests, HTML reports on GitHub Pages, and comprehensive quality gates\n\n**Included Examples:**\n\nThe template includes two complete challenge implementations demonstrating real-world patterns:\n\n- **UITestingPlayground** — 23 scenarios covering element identification, timing, interactions, and advanced UI challenges\n- **AutomationExercise** — 15 e-commerce scenarios including authentication, product browsing, cart management, checkout, and account features\n\n### Key Features\n\n- ✓ **Zero separate step-definition files** — Decorators (`@Given`, `@When`, `@Then`) directly on POM methods\n- ✓ **Built-in axe-core accessibility** — WCAG compliance checks in every test run\n- ✓ **Lighthouse performance audit** — Core Web Vitals and performance metrics in CI\n- ✓ **Performance load testing** — Artillery-powered load tests for API performance validation\n- ✓ **Bun runtime** — 3–5× faster installs \u0026 test runs vs Node.js\n- ✓ **Cursor.rules + MCP config** — Composer understands your project instantly\n- ✓ **Parallel + sharded GitHub Actions** — Optimized CI/CD out of the box\n- ✓ **Beautiful HTML reports** — Published to GitHub Pages with traces, screenshots, videos\n- ✓ **TypeScript with strict mode** — Full type safety throughout\n- ✓ **Comprehensive code quality** — ESLint, Prettier, CSpell, Husky, Conventional Commits\n- ✓ **Multi-environment support** — Development, staging, production via .env files\n- ✓ **Local CI/CD testing** — Act integration for testing workflows before pushing\n\n---\n\n## Test Scenarios\n\n**📚 Challenge Documentation**: For comprehensive details on each challenge, see:\n\n- **[UITestingPlayground Challenge Documentation](./docs/uitestingplayground-challenge.md)** - Complete guide to all 23 scenarios\n- **[AutomationExercise Challenge Documentation](./docs/automationexercise-challenge.md)** - Complete guide to all 15 scenarios\n- **[JSONPlaceholder API Challenge Documentation](./docs/jsonplaceholder-challenge.md)** - Complete guide to all 34 API scenarios\n- **[ReqRes.in API Challenge Documentation](./docs/reqres-challenge.md)** - Complete guide to all 13 authentication and pagination API scenarios\n\n### UITestingPlayground Challenge\n\nThis challenge showcases **23 comprehensive test scenarios** from [UITestingPlayground](http://uitestingplayground.com/), demonstrating various automation challenges and best practices. See the [full challenge documentation](./docs/uitestingplayground-challenge.md) for exhaustive details.\n\n### Element Identification (5 scenarios)\n\n- **Dynamic ID** - Click button without relying on dynamic IDs\n- **Class Attribute** - Handle complex class attributes with special characters\n- **Verify Text** - Find elements with text split across DOM nodes\n- **Non-Breaking Space** - Handle non-breaking spaces in text matching\n- **Sample App** - Login flow with dynamically generated attributes\n\n### Timing \u0026 Synchronization (7 scenarios)\n\n- **Load Delay** - Wait for page elements to load\n- **AJAX Data** - Handle elements appearing after AJAX requests\n- **Client Side Delay** - Wait for client-side JavaScript calculations\n- **Progress Bar** - Monitor and interact with progress indicators\n- **Animated Button** - Wait for animations to complete\n- **Disabled Input** - Wait for input fields to become enabled\n- **Auto Wait** - Wait for elements to become interactable\n\n### Interaction Challenges (5 scenarios)\n\n- **Click** - Handle buttons that ignore DOM click events\n- **Text Input** - Enter text using physical keyboard input\n- **Mouse Over** - Handle DOM changes triggered by hover events\n- **Scrollbars** - Scroll elements into view before interaction\n- **Overlapped Element** - Handle elements covered by other elements\n\n### Advanced Challenges (6 scenarios)\n\n- **Dynamic Table** - Extract and verify values from dynamic tables\n- **Shadow DOM** - Interact with elements inside Shadow DOM\n- **Visibility** - Verify element visibility states (opacity, display, position)\n- **Hidden Layers** - Handle z-order stacking and overlapped elements\n- **Alerts** - Accept/dismiss browser dialogs and prompts\n- **File Upload** - Upload files through iframe-based file inputs\n\nAll scenarios are implemented using **BDD (Gherkin)** feature files and **Page Object Model (POM)** patterns with TypeScript decorators.\n\n### AutomationExercise Challenge\n\nThis challenge implements **15 comprehensive e-commerce test scenarios** covering the complete user journey from registration to order completion. See the [full challenge documentation](./docs/automationexercise-challenge.md) for exhaustive details.\n\n**Implemented Features**:\n\n- **User Authentication** (3 scenarios) — Registration, login, logout with API-backed user provisioning\n- **Product Browsing** (3 scenarios) — Product listing, search, and detailed product views\n- **Shopping Cart** (3 scenarios) — Add, view, and remove products from cart\n- **Checkout Process** (2 scenarios) — Order placement, payment processing, and confirmation\n- **User Account Management** (2 scenarios) — Account dashboard and profile updates\n- **Contact \u0026 Support** (2 scenarios) — Contact form submission with file uploads\n\n**Key Platform Handling**:\n\n- **Cookie Consent Modal** — Automatic dismissal of `fc-consent` overlay\n- **Interstitial Ads** — Detection and recovery from `google_vignette` redirects\n- **User Provisioning** — API client for programmatic account creation\n- **Test Data Generation** — Unique, realistic user data for each test run\n\n### JSONPlaceholder API Challenge\n\nThis challenge demonstrates **34 comprehensive API test scenarios** using [JSONPlaceholder](https://jsonplaceholder.typicode.com/), covering all 6 resources (Posts, Users, Comments, Albums, Photos, Todos) with full CRUD operations and relationship queries. See the [full challenge documentation](./docs/jsonplaceholder-challenge.md) for exhaustive details.\n\n**Implemented Resources**:\n\n- **Posts** (5 scenarios) — Blog post CRUD operations\n- **Users** (5 scenarios) — User management operations\n- **Comments** (6 scenarios) — Comment operations with post relationships\n- **Albums** (6 scenarios) — Album operations with user relationships\n- **Photos** (6 scenarios) — Photo operations with album relationships\n- **Todos** (6 scenarios) — Todo operations with completion status\n\n**Key Features**:\n\n- **API Object Model (AOM)** — Service classes following POM pattern for APIs\n- **Shared Utilities** — Response verification, tracking, validation, and data generation\n- **Relationship Queries** — Test nested resources (e.g., comments by post, albums by user)\n- **No Browser Required** — Pure API testing without browser launch overhead\n\n### ReqRes.in API Challenge\n\nThis challenge demonstrates **authentication and pagination testing patterns** using [ReqRes.in](https://reqres.in/), a hosted REST API for testing. See the [full challenge documentation](./docs/reqres-challenge.md) for exhaustive details.\n\n**Implemented Features**:\n\n- **Authentication** (4 scenarios) — Login and registration flows with token management\n- **Users API** (6 scenarios) — User CRUD operations and pagination\n- **Pagination** (3 scenarios) — Testing paginated data retrieval\n\n**Total**: 13 test scenarios\n\n**Key Features**:\n\n- **Token Management** — Utility for managing authentication tokens\n- **Authentication Service** — Login and registration patterns\n- **Pagination Testing** — Comprehensive pagination validation\n- **No Browser Required** — Pure API testing using `APIRequestContext`\n\n### Performance Load Testing\n\nThis project includes **comprehensive performance/load testing** using Artillery with Playwright engine. Load tests validate API performance under various load conditions and are integrated into CI/CD workflows. See the [full performance testing documentation](./docs/performance-testing.md) for exhaustive details.\n\n**Implemented Challenges**:\n\n- **JSONPlaceholder Load Tests** — Load tests for all 6 resources (posts, users, comments, albums, photos, todos)\n- **ReqRes.in Load Tests** — Authenticated and paginated API load tests\n- **HTTPBin Load Tests** — HTTP method-specific load testing\n\n**Key Features**:\n\n- **Artillery Integration** — Load testing with Playwright engine\n- **Per-Endpoint Thresholds** — Configurable performance thresholds per resource/endpoint\n- **Multiple Test Types** — Normal load, stress, and spike test scenarios\n- **CI/CD Integration** — Runs on every push and publishes reports to GitHub Pages\n- **No Browser Required** — API load testing without browser overhead\n\n---\n\n## Test Reports\n\n![Test Reports Dashboard](docs/images/dashboard.png)\n\nCheck 👉🏼 [GitHub Pages HTML Report](https://m3au.github.io/playwright-bdd-cursor-template/) for the _**Interactive HTML reports**_ generated automatically from Playwright test runs, including test results, traces, screenshots, accessibility/performance audit reports, and performance load test results.\n\nView workflow runs 👉🏼 [GitHub Actions](https://github.com/m3au/playwright-bdd-cursor-template/actions), we're running **85 E2E test scenarios** (23 UITestingPlayground + 15 AutomationExercise + 34 JSONPlaceholder API + 13 ReqRes.in API) and **performance load tests** for JSONPlaceholder, ReqRes.in, and HTTPBin APIs using 2 shards (WORKERS=50% per shard).\n\n---\n\n## Documentation\n\nComprehensive documentation covering architecture, development workflows, code quality tools, AI assistance configuration, challenge implementations, and project goals. All documentation is located in the `docs/` directory.\n\n### Challenge Documentation\n\n- **[UITestingPlayground Challenge](./docs/uitestingplayground-challenge.md)** - Complete guide to all 23 UI testing scenarios, implementation details, and patterns\n- **[AutomationExercise Challenge](./docs/automationexercise-challenge.md)** - Complete guide to all 18 e-commerce scenarios, user flows, and utilities\n- **[JSONPlaceholder API Challenge](./docs/jsonplaceholder-challenge.md)** - Complete guide to all 34 API testing scenarios, AOM patterns, and utilities\n- **[ReqRes.in API Challenge](./docs/reqres-challenge.md)** - Complete guide to authentication and pagination API testing patterns\n\n### Project Documentation\n\n- **[CLAUDE.md](./CLAUDE.md)** - AI assistant development guide with project-specific patterns and critical notes\n- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines, development workflow, and code style\n- **[Architecture Documentation](./docs/architecture.md)** - System architecture, design decisions, and diagrams\n- **[Development Guide](./docs/development.md)** - Development setup, guidelines, and best practices\n- **[Code Quality Files](./docs/code-quality.md)** - Reference guide for all code quality configuration files\n- **[AI Tuning](./docs/ai-tuning.md)** - Cursor IDE rules and AI assistant configuration\n- **[Act Testing](./docs/act-testing.md)** - Local GitHub Actions workflow testing with act\n- **[Changelog](./CHANGELOG.md)** - Complete version history and release notes\n\n---\n\n## Project Structure\n\nA high-level view of the project's directory structure:\n\n```text\nplaywright-bdd-cursor-template/\n├── .cursor/                          # Cursor IDE configuration\n│   ├── mcp.json                      # MCP servers (Playwright, GitHub)\n│   ├── hooks/                        # Example hook scripts (copy to ~/.cursor/hooks/ to use)\n│   └── rules/                        # Cursor rules (commits, comments, testing, etc.)\n├── **.github/**                      # GitHub configuration\n│   ├── **workflows/**                # CI/CD workflows (GitHub Actions)\n│   │   ├── ci.yml                    # Main CI orchestrator workflow + report publishing\n│   │   ├── preflight.yml             # Pre-flight checks (lint + unit tests)\n│   │   ├── test.yml                  # E2E tests workflow\n│   │   ├── lighthouse.yml            # Lighthouse audit workflow\n│   │   ├── axe.yml                   # Axe audit workflow\n│   │   ├── performance.yml           # Performance load tests workflow\n│   │   └── dependabot.yml            # Dependabot workflow (pins versions on PRs)\n│   ├── dependabot.yml                # Dependabot configuration (dependency updates)\n│   └── templates/                    # Report templates (HTML)\n├── .husky/                           # Git hooks (pre-commit, commit-msg, prepare-commit-msg, pre-push)\n├── **tests/**                        # All test suites\n│   ├── **e2e/**                      # End-to-end tests\n│   │   ├── challenges/               # Challenge-specific test suites\n│   │   │   ├── uitestingplayground/  # UITestingPlayground challenge\n│   │   │   │   ├── features/         # Gherkin feature files\n│   │   │   │   └── poms/             # Page Object Models with decorators\n│   │   │   │       ├── components/   # Reusable component POMs\n│   │   │   │       └── pages/        # Page POMs\n│   │   │   ├── automationexercise/   # AutomationExercise challenge\n│   │   │   │   ├── features/         # Gherkin feature files\n│   │   │   │   └── poms/             # Page Object Models with decorators\n│   │   │   │       └── pages/        # Page POMs\n│   │   │   ├── jsonplaceholder/      # JSONPlaceholder API challenge\n│   │   │   │   ├── features/          # Gherkin feature files\n│   │   │   │   ├── services/         # API Object Models (AOM)\n│   │   │   │   └── utils/            # API testing utilities\n│   │   │   └── reqres/               # ReqRes.in API challenge\n│   │   │       ├── features/          # Gherkin feature files\n│   │   │       ├── services/         # API Object Models (AOM)\n│   │   │       └── utils/            # API testing utilities\n│   │   └── **world.ts**              # Playwright fixtures, test setup, and environment config\n│   ├── **performance/**              # Performance/load tests\n│   │   ├── challenges/               # Challenge-specific load test suites\n│   │   │   ├── jsonplaceholder/      # JSONPlaceholder load tests\n│   │   │   ├── reqres/               # ReqRes.in load tests\n│   │   │   └── httpbin/              # HTTPBin load tests\n│   │   ├── utils/                    # Performance testing utilities\n│   │   └── world.ts                  # Performance test fixtures\n│   ├── utils/                        # Shared utility functions\n│   ├── unit/                         # Unit tests (100% coverage)\n│   └── audit/                        # Audit tests (axe, lighthouse)\n├── **scripts/**                      # Utility scripts\n│   ├── bump-version.ts               # Automatic version bumping\n│   ├── changelog.ts                  # Changelog generation\n│   ├── generate-challenge-summary.ts # Challenge summary generation\n│   ├── lint.ts                       # Unified linting: TypeScript → ESLint → ShellCheck\n│   ├── pin-versions.ts               # Dependency version pinning\n│   └── update-coverage-badge.ts      # Coverage badge update\n├── docs/                             # Documentation\n├── Makefile                          # Make targets for local workflow testing\n├── package.json                      # Dependencies and scripts\n├── bun.lock                          # Bun lock file (pinned dependency versions)\n├── bunfig.toml                       # Bun package manager configuration\n├── playwright.config.ts              # Playwright E2E configuration\n├── eslint.config.ts                   # ESLint configuration\n├── prettier.config.ts                 # Prettier configuration\n├── tsconfig.json                     # TypeScript configuration\n├── main.code-workspace               # VS Code workspace configuration\n├── .cspell.jsonc                     # Spell checker configuration\n├── .markdownlint.jsonc               # Markdown linting configuration\n├── .lintstagedrc.json                # lint-staged configuration\n├── .prettierignore                   # Prettier ignore patterns\n├── .editorconfig                     # Editor configuration (indentation, encoding)\n├── .gitignore                        # Git ignore patterns\n├── .gitattributes                    # Git attributes (line endings, file types)\n├── .cursorignore                     # Cursor IDE ignore patterns\n├── .nvmrc                            # Node version manager version\n├── .env                              # Environment variables (local, gitignored)\n├── .env.example                      # Environment variables template\n├── .env.production                   # Production environment variables template\n├── LICENSE                           # License file\n└── README.md                         # This file\n```\n\n---\n\n## Quick Start\n\n**Get started in under 60 seconds:**\n\n```bash\n# Clone and install\ngit clone https://github.com/m3au/playwright-bdd-cursor-template.git\ncd playwright-bdd-cursor-template\nbun install\n\n# Configure (copy .env.example to .env)\ncp .env.example .env\n\n# Run your first test\nbun run test\n```\n\n**That's it!** Your tests are running. 🎉\n\n**Common Commands:**\n\n```bash\nbun run test                    # Run all E2E tests\nbun run test:automationexercise  # Run specific challenge\nbun run test:uitestingplayground # Run specific challenge\nbun run test:jsonplaceholder     # Run JSONPlaceholder API challenge\nbun run test -- --project=reqres-api  # Run ReqRes.in API challenge\nbun run test:performance         # Run all performance load tests\nbun run test:performance:jsonplaceholder  # Run JSONPlaceholder load tests\nbun run test -- --project=reqres-performance  # Run ReqRes.in load tests\nbun run test -- --project=httpbin-performance  # Run HTTPBin load tests\nbun test                        # Run unit tests with coverage\nbun ui                          # Interactive Playwright UI\nbun axe                         # Accessibility audit\nbun lighthouse                  # Performance audit\nbun lint                        # Run all linting checks\n```\n\nSee [Development Guide](./docs/development.md#environment-configuration) for complete environment variable documentation.\n\n**Code Quality:**\n\n```shell\nbun lint              # Run all linting: TypeScript → ESLint → ShellCheck\nbun lint:fix          # Fix ESLint errors (TS, JSON, HTML, Markdown, YAML)\nbun lint:typescript   # TypeScript type checking only\nbun lint:eslint       # ESLint only (TS, JSON, HTML, Markdown, YAML, .mdc)\nbun lint:markdown     # Markdown linting only\nbun lint:shellcheck   # ShellCheck only (Husky git hooks)\n```\n\n**Local CI/CD Testing:**\n\nTest GitHub Actions workflows locally using the Makefile (requires Docker and act):\n\n```shell\nmake test        # Test E2E tests workflow locally\nmake lighthouse  # Test Lighthouse audit workflow locally\nmake axe         # Test Axe audit workflow locally\nmake ci          # Test main CI workflow locally\nmake help        # Show all available workflow test targets\n```\n\n## Architecture \u0026 Patterns\n\n### Challenge-Based Organization\n\nEach challenge is isolated in its own folder under `tests/e2e/challenges/`, containing:\n\n- Feature files (`features/*.feature`)\n- Page Object Models (`poms/pages/` and `poms/components/`)\n- Challenge-specific configuration (`world.ts`)\n\nThis structure allows for easy addition of new challenges without affecting existing ones.\n\n### Page Object Model (POM)\n\nPOMs are located within each challenge folder (e.g., `tests/e2e/challenges/uitestingplayground/poms/`).\n\n**Key Features:**\n\n- **BDD decorators** (`@Given`, `@When`, `@Then`) are applied directly to POM methods\n- Eliminates separate step definition files\n- POMs are automatically registered as fixtures using `@Fixture` decorator\n\n### World Fixture\n\nThe `tests/e2e/world.ts` file is the central hub that:\n\n**Extends Playwright-BDD:**\n\n- Extends the standard `playwright-bdd` test\n- Registers all POMs from all challenges using `@Fixture` decorator\n\n**Provides Core Exports:**\n\n- BDD decorators: `@Fixture`, `@Given`, `@When`, `@Then`\n- Playwright types: `expect`, `Locator`, `Page`\n- Custom `@Step` decorator (for internal step definitions)\n\n**Environment Configuration:**\n\n- `getEnvironment()` - Loads environment-specific configuration data\n- `environment(name)` - Accesses environment variables directly\n\n**Configuration Requirements:**\n\nEach challenge must define its own `BASE_URL_\u003cCHALLENGE\u003e` variable (accessed via `environment(\\`BASE*URL*${challengeName.toUpperCase()}\\`)!`):\n\n- `BASE_URL_UITESTINGPLAYGROUND`\n- `BASE_URL_AUTOMATIONEXERCISE`\n- `BASE_URL_JSONPLACEHOLDER`\n- `BASE_URL_REQRES`\n\n### BDD with Gherkin\n\nFeature files are located within each challenge folder. Test files are automatically generated to `test-output/bdd-gen/`.\n\n**UITestingPlayground Features:**\n\n- `element-identification.feature` - 5 scenarios\n- `timing-synchronization.feature` - 7 scenarios\n- `interaction-challenges.feature` - 5 scenarios\n- `advanced-challenges.feature` - 6 scenarios\n\n**JSONPlaceholder API Features:**\n\n- `posts.feature` - 5 scenarios\n- `users.feature` - 5 scenarios\n- `comments.feature` - 6 scenarios\n- `albums.feature` - 6 scenarios\n- `photos.feature` - 6 scenarios\n- `todos.feature` - 6 scenarios\n\n**ReqRes.in API Features:**\n\n- `authentication.feature` - 4 scenarios (currently skipped due to API 401 responses)\n- `users.feature` - 6 scenarios (3 skipped for write operations)\n- `pagination.feature` - 3 scenarios\n\n## AI Assistance\n\nThis project is configured for AI-assisted development with Cursor IDE. Rules guide AI assistants to follow project conventions and maintain code quality.\n\n**Configuration:**\n\n- Rules automatically apply when editing files (context-aware based on file patterns)\n- Use `@browser` for browser automation, `@playwright` for Playwright test features\n- Configuration files: `.cursor/rules/` (rules), `.cursor/mcp.json` (MCP servers), `.cursorignore` (context exclusion)\n\n---\n\n## Code Quality\n\nThis project uses comprehensive code quality tooling:\n\n- **ESLint** (`eslint.config.ts`) - Linting with TypeScript, SonarJS, Unicorn, CSpell, Playwright, Import, Promise, Security, Regexp, No-Secrets, Perfectionist, JSON, HTML, YAML, and Markdown support\n- **ShellCheck** - Shell script linting for Husky git hooks\n- **Prettier** (`prettier.config.ts`) - Code formatting\n- **TypeScript** (`tsconfig.json`) - Type checking with strict mode\n- **CSpell** (`.cspell.jsonc`) - Spell checking (English, German, TypeScript)\n- **EditorConfig** (`.editorconfig`) - Editor configuration for consistent formatting\n- **Git Attributes** (`.gitattributes`) - Consistent line endings and file handling\n- **Husky** (`.husky/`) - Git hooks (pre-commit, commit-msg, pre-push, prepare-commit-msg)\n- **lint-staged** (`.lintstagedrc.json`) - Staged file linting\n- **Conventional Commits** - Commit message format validation\n\n**Git Hook Actions:**\n\n- **Pre-commit**: Runs **unit tests**, then executes **lint-staged** (ESLint, Prettier, ShellCheck) on only the staged files for speed\n- **Commit-msg**: Validates conventional commit format\n- **Prepare-commit-msg**: Automatically calculates the next **Semantic Version** and updates the `CHANGELOG.md` based on your commit message\n- **Pre-push**: TypeScript type checking\n- **CI/CD**: Runs all quality gates automatically (pre-flight checks run first: lint + unit tests, then E2E/audits)\n\n**Editor Integration:**\n\n- **Format on Save**: Enabled via VS Code workspace settings (Prettier for all files)\n- **ESLint**: Auto-fix on save enabled (TS, JS, Markdown via @eslint/markdown)\n- **TypeScript**: Real-time type checking\n- **CSpell**: Spell checking integrated into ESLint\n- **EditorConfig**: Consistent formatting across editors\n\n**IDE-Agnostic Configuration:**\n\nThis repository is designed to work with any IDE or editor. Universal configuration files ensure consistent formatting and behavior:\n\n- **`.editorconfig`** - Works with all major editors (VS Code, IntelliJ, Vim, etc.)\n- **`.gitattributes`** - Ensures consistent line endings (LF) and whitespace handling across platforms\n- **`.prettierrc`** / `prettier.config.ts` - Formatting rules (works with Prettier extensions in any editor)\n- **`.typos.toml`** - Typo detection configuration (works with `typos` CLI tool)\n- **`.coderabbit.yaml`** - CodeRabbit AI PR review configuration (GitHub integration)\n\n**Optional IDE-Specific Files:**\n\n- **`main.code-workspace`** - VS Code workspace configuration (optional, for VS Code users)\n  - Includes recommended extensions, format-on-save, and Cucumber/Gherkin support\n  - Not required - all functionality works without it\n- **`.cursor/rules/`** - Cursor IDE-specific AI rules (can be adapted for other AI assistants)\n\n**Automatic Versioning:**\n\nVersion bumping and changelog generation happen automatically on commit:\n\n- `feat:` commits → Minor version bump + changelog entry\n- `fix:` commits → Patch version bump + changelog entry\n- `perf:` commits → Patch version bump + changelog entry (performance improvements)\n- `refactor:` commits → Patch version bump + changelog entry (code refactoring)\n- `BREAKING CHANGE` → Major version bump + changelog entry\n- Other commit types (`docs:`, `style:`, `test:`, `chore:`, `ci:`, `build:`) → No version bump\n\nSee [CHANGELOG.md](./CHANGELOG.md) for complete version history.\n\n---\n\nCreated with ❤️ by mū ([m3au](https://github.com/m3au))\n\n\u003cimg src=\"https://avatars.githubusercontent.com/u/2736565?v=4\" width=\"48\" height=\"48\" alt=\"m3au\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm3au%2Fplaywright-bdd-cursor-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm3au%2Fplaywright-bdd-cursor-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm3au%2Fplaywright-bdd-cursor-template/lists"}