viktor-silakov/bdd-best-practices
Overview
This skill audits BDD (Gherkin) + Playwright test solutions for spec quality, flake resistance, selector strategy, accessibility-friendly locators, and AI-agent operability. It produces weighted aspect scores, an overall grade, categorized issues with evidence and effort estimates, and a prioritized improvement roadmap. The workflow adapts to repository size and can offer interactive quick fixes for low-effort critical problems.
How this skill works
The auditor auto-discovers stack, repo size, CI and artifact settings, then analyzes feature files and step definitions (sampling for medium/large codebases). It scores eight aspects using defined rubrics and generates a terminal dashboard plus machine- and human-readable reports. For medium/large repos it shows progress, saves history, and can propose semantic/a11y refactors and an actionable phased roadmap.
When to use it
- Assess test suite stability after recurring flakes or CI failures
- Prepare tests for run by AI agents or cross-team automation
- Prioritize and plan refactors to improve maintainability and selector quality
- Validate Playwright test architecture, waiting strategies, and artifact settings
- Generate an actionable improvement roadmap for medium/large suites
Best practices
- Auto-detect environment and ask only minimal questions based on repo size
- Score across multiple aspects to avoid single-metric fixes
- Prioritize quick wins (remove sleeps, enable trace-on-failure) before deep refactors
- Use stratified sampling for large suites to keep analysis performant
- Provide evidence, impact, and effort estimate for every issue to aid triage
Example use cases
- Run a stability audit after intermittent CI failures to find flaky waits and fragile selectors
- Evaluate readiness of tests for AI-agent-driven debugging or maintenance
- Generate a phased roadmap when migrating CSS selectors to semantic/getByRole locators
- Apply automated quick fixes for low-effort critical issues like replacing hard sleeps
- Produce machine-readable reports for tracking improvement over time
FAQ
Small repos (≤20 scenarios) complete quickly; medium/large times scale with sampled scenario count and show progress for transparency.
Will the auditor modify code automatically?
It offers interactive quick fixes only for clear, low-effort patterns; changes are shown as diffs and applied only with user confirmation.
