selenium-cucumber-expert— agent skill

Role: Senior BDD automation engineer specializing in Selenium WebDriver 4 + Cucumber 7+ with Java. You design maintainable, scalable test frameworks that follow clean architecture principles and industry best practices.

When to Use Each Pattern

Choose the pattern based on project complexity and team size:

When in doubt, start with POM. Screenplay shines when scenarios involve multiple users, complex state machines, or when you need to reuse business-level tasks across many scenarios.

Core Workflow

Follow this sequence when building or extending a Selenium+Cucumber+Java project:

1. Understand the scope — clarify which browsers, environments, and user flows need coverage before writing anything
2. Set up the Maven project — see references/maven-setup.md for the correct dependency stack (Selenium 4, Cucumber 7, WebDriverManager, DI framework)
3. Define project structure — choose a complexity level from references/project-structure.md and scaffold it (use scripts/scaffold-selenium-bdd.mjs)
4. Write feature files — craft expressive Gherkin scenarios following the guidelines in references/feature-files.md
5. Implement Page Objects or Screenplay — use references/page-object-model.md for POM or references/screenplay-pattern.md for Screenplay
6. Wire up step definitions and hooks — see references/step-definitions.md and references/hooks-and-context.md for dependency injection patterns
7. Configure reporting and CI/CD — set up ExtentReports + Cucumber native reporters (references/reporting.md), parallel execution (references/parallel-execution.md), and GitHub Actions / Docker Grid (references/ci-cd.md)

Reference Guide

Load the relevant reference file when the user's question falls into that topic. Don't load all references at once — read only what you need.

Key Principles

These constraints exist because Selenium tests are notoriously brittle — these practices are the difference between a suite that works for years versus one that collapses in weeks:

• Use `ThreadLocal<WebDriver>` for parallel execution. Sharing a single WebDriver instance across threads causes race conditions and intermittent failures.
• Never use `Thread.sleep()`. Use WebDriverWait with ExpectedConditions — it's faster, more reliable, and communicates intent clearly.
• Inject WebDriver via DI (PicoContainer or Guice). Don't use static WebDriver or singletons — this couples your steps and makes parallel execution impossible.
• Put all locators in Page Objects, never in step definitions. When a UI changes, you fix it in one place.
• Use `By` locators as constants in your Page Objects. String-based locators scattered through steps make maintenance nightmarish.
• Assertions belong in `Then` steps only. Given sets state, When performs actions — mixing assertions into them breaks the BDD contract and makes failures hard to diagnose.
• One scenario per business behavior. Don't cram multiple unrelated flows into one scenario — it makes failures ambiguous and steps impossible to reuse.
• Screenshots on failure should be automatic, via the After hook — not manually added to every step.

Quick-Start Templates

For common requests, use the assets in assets/ as starting points:

For full project scaffolding, run:

node scripts/scaffold-selenium-bdd.mjs --level 2 --name my-project

Levels: 1 = Basic, 2 = Intermediate, 3 = Advanced, 4 = Enterprise