The Harsh Truth About BDD: Why Your .feature Files Are a Maintenance Nightmare

The Acceptance Test Framework That Promised Collaboration and Delivered Pain

Valentina Jemuovic, an expert in ATDD and TDD who helps teams safely modernize legacy code, triggered a heated debate with 61 reactions and 28 comments when she wrote: “If you’ve ever written acceptance tests in plain-text Gherkin, you probably had the same thought: ‘This looks clean… so why is it so painful to maintain?’ Gherkin was supposed to let product owners write specifications. But in reality? Almost never happens. Developers write the .feature files. Developers maintain them. Developers debug them at runtime.”

The promise of BDD was beautiful: product owners write human-readable specifications in Given/When/Then format, developers implement the step definitions, and the specifications become living documentation that is both executable and understandable by non-technical stakeholders. The reality, after a decade of industry experience, is far more complicated.

The Three Painful Problems Nobody Warned You About

Problem 1: Duplication Everywhere

Gherkin step definitions are matched by regular expressions against plain-text steps. This creates a combinatorial explosion of similar-but-not-identical steps across feature files. “Given a user is logged in” and “Given the user has logged in” and “Given I am logged in as a user” are three different steps that do the same thing — but each needs its own step definition or a regex flexible enough to match all three.

In a large test suite with hundreds of scenarios, this duplication becomes unmanageable. Teams spend more time maintaining step definition libraries than writing new tests. Refactoring a single step can break dozens of scenarios across multiple feature files because the coupling is invisible — it happens through string matching, not code references.

Problem 2: Typos Equal Runtime Failures

In Gherkin, a single character typo in a step does not produce a compile-time error. It produces a runtime error — “Step definition not found.” Your IDE cannot help you because .feature files are plain text. Your compiler cannot help you because there is no compilation step. You discover the typo only when you run the test, which might be minutes or hours later in a CI pipeline.

Compare this to a standard Playwright test where a typo in a method call produces an immediate red squiggly line in your IDE, a TypeScript compilation error, and a clear message telling you exactly what went wrong and where. The feedback loop in Gherkin is orders of magnitude slower than in typed test code.

Problem 3: No Real IDE Support

Modern IDEs provide autocomplete, type checking, refactoring tools, and navigation for code files. For .feature files, you get… syntax highlighting. Maybe a plugin that attempts step definition navigation, but it is unreliable because the matching is regex-based and context-dependent.

You cannot right-click a step and “Go to Definition” reliably. You cannot rename a step and have it automatically update across all feature files. You cannot use “Find All References” to see where a step definition is used. Every refactoring is manual, error-prone, and requires running the entire suite to verify nothing broke.

The Honest Assessment: When BDD Actually Works

BDD and Gherkin are not universally bad. They work well in specific contexts. If your product owner genuinely reads and contributes to .feature files (rare, but it happens in some regulated industries), the collaboration benefit is real. If your scenarios are high-level business flows with minimal variation, the duplication problem stays manageable. If your team is small and disciplined about step definition standards, maintenance overhead stays low.

BDD also works well as a conversation framework — using Given/When/Then to structure requirement discussions during sprint planning — even if you never write .feature files. The thinking pattern is valuable. The file format is where the problems live.

When to Avoid Gherkin

Avoid Gherkin when your product owners do not read .feature files (which means you are maintaining a DSL for an audience of zero), when your test suite has more than 200 scenarios (duplication becomes unmanageable), when your application has complex data-driven scenarios that require parameterization (Gherkin’s Scenario Outline handles this poorly), or when your QA team has strong programming skills and would be more productive writing tests directly in code.

The Alternatives: Compile-Time Safe Acceptance Testing

The core idea behind BDD — readable, business-focused test specifications — does not require Gherkin or .feature files. Several approaches provide the same readability with compile-time safety.

Fluent API test patterns use method chaining to create readable test code that looks almost like natural language but with full IDE support, type checking, and refactoring capability. Playwright’s built-in API already supports this pattern naturally.

ATDD (Acceptance Test-Driven Development) focuses on writing acceptance criteria as executable tests before development begins — but using your actual test framework instead of a separate DSL. The acceptance criteria live in test code, not in .feature files, which means they get all the benefits of the programming language’s tooling.

Test description patterns use descriptive test names and well-structured arrange/act/assert patterns to make tests self-documenting without an intermediary language layer.

Migration Guide: From Brittle Gherkin to Maintainable Tests

If your team is currently using Gherkin and experiencing the pain points described above, here is a practical migration path that does not require rewriting everything at once.

Phase 1: Stop writing new .feature files. All new tests go into the standard test framework (Playwright, Cypress, etc.) using descriptive test names that capture the same business intent as Gherkin scenarios.

Phase 2: Identify high-maintenance scenarios. Find the .feature files that break most often, have the most step definition duplication, or take the longest to maintain. These are your migration candidates.

Phase 3: Convert incrementally. For each migration candidate, rewrite it as a standard test file. Use the existing step definition code — you are moving the orchestration from Gherkin to your test framework, not rewriting the underlying automation.

Phase 4: Retire unused step definitions. As feature files are migrated, delete the step definitions they used. Track unused step definitions and clean them up regularly to prevent the library from becoming legacy code.

What This Article Cannot Tell You

I cannot tell you that BDD is always wrong. For some teams in some contexts, it genuinely improves collaboration and documentation. I also cannot tell you that migrating away from Gherkin is risk-free — any migration introduces temporary instability and requires team alignment. What I can tell you is that the maintenance cost of Gherkin scales poorly, and if your team is experiencing the pain points described here, the alternatives deserve serious evaluation.

Frequently Asked Questions

My team loves Gherkin. Should I force a migration?

No. If your team is productive and the maintenance burden is manageable, Gherkin is working for you. The problems described in this article manifest primarily in large, long-lived test suites. If your suite is small and your team is disciplined, Gherkin’s drawbacks may not outweigh its readability benefits.

Can Cucumber/SpecFlow be improved to fix these issues?

Some issues are inherent to the architecture (string-matched step definitions, plain-text parsing) and cannot be fully fixed without fundamental changes. Better IDE plugins, stricter step definition naming conventions, and shared step libraries can reduce the pain but not eliminate it. The core problem — an extra abstraction layer between your tests and your code — remains.

How do I maintain stakeholder visibility without .feature files?

Use test report generators that produce readable output from your standard tests. Tools like Allure Report, Playwright’s built-in HTML reporter, and custom report templates can present test results in business-friendly language without requiring Gherkin as the input format. Descriptive test names like “should allow user to complete checkout with valid credit card” are readable by any stakeholder.

References

• Valentina Jemuovic — BDD Gherkin Critique Post (LinkedIn, 61 reactions)
• Cucumber — BDD Official Guide
• Martin Fowler — Given When Then
• Playwright — Test Annotations and Descriptions
• SpecFlow — BDD Benefits and Limitations
• Ministry of Testing — BDD and Cucumber Best Practices
• Dan North — Introducing BDD (Original Article)
• Agile Alliance — ATDD