Acceptance Testing / BDD (Behat)
debt(d7/e5/b5/t5)
Closest to 'only careful code review or runtime testing' (d7). The absence of acceptance tests is not something a compiler or standard linter catches. Tools like Behat, Codeception, Playwright, or Cypress exist but they don't automatically detect *missing* acceptance tests — they only run tests that already exist. Detecting that critical user journeys lack acceptance test coverage requires manual code review, process audits, or custom CI checks. The detection_hints confirm automated=no.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix suggests writing Behat scenarios for 5-10 critical user journeys, which is not a one-line patch — it requires creating test infrastructure (Behat configuration, feature files, step definitions, context classes), setting up a production-like test environment, and writing multiple scenario files. This is a significant but localized effort within the testing layer, not an architectural rework.
Closest to 'persistent productivity tax' (b5). Acceptance tests impose ongoing maintenance costs: they are slow (as noted in common_mistakes), require production-like environments, are prone to flakiness, and must be updated whenever critical user journeys change. They apply across the web context and affect CI/CD pipelines, release processes, and multiple team workflows. However, they don't define the system's architecture — they sit alongside it as a testing layer.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field explicitly states the trap: developers commonly believe acceptance tests are just end-to-end tests with a different name, confusing technical scope with business intent. This leads to common mistakes like writing tests with technical assertions instead of business-readable scenarios, over-testing every feature instead of critical journeys, and not involving stakeholders. It's a well-documented gotcha but not catastrophic — most teams learn the distinction with experience.
Also Known As
TL;DR
Explanation
Acceptance testing verifies that a feature behaves correctly from the end user's perspective, not just unit-level correctness. Behaviour-Driven Development (BDD) uses Gherkin syntax (Given/When/Then) to write human-readable scenarios that are both documentation and automated tests. Behat is PHP's primary BDD framework — Gherkin feature files are executed against step definitions written in PHP, often driving a real browser via Mink (Selenium, Playwright). Acceptance tests sit at the top of the Test Pyramid — they are slow, brittle if UI-dependent, but catch integration gaps that unit tests miss. Write them for critical user journeys: checkout flow, user registration, payment processing.
Diagram
flowchart TD
subgraph BDD_Cycle
STORY[User story<br/>As a user I want to...]
SCENARIO2[Gherkin scenario<br/>Given When Then]
BEHAT[Behat runs scenario]
FEATURE[Feature works end-to-end]
STORY --> SCENARIO2 --> BEHAT --> FEATURE
end
subgraph Layers
UNIT2[Unit tests - fast isolated]
INTEGRATION2[Integration - real DB]
ACCEPTANCE[Acceptance - full user journey<br/>slowest most valuable]
UNIT2 --> INTEGRATION2 --> ACCEPTANCE
end
style FEATURE fill:#238636,color:#fff
style ACCEPTANCE fill:#6e40c9,color:#fff
style UNIT2 fill:#1f6feb,color:#fff
Watch Out
Common Misconception
Why It Matters
Common Mistakes
- Too many acceptance tests — they are slow; use them for critical user journeys, not every feature.
- Acceptance tests with no domain language — technical assertions instead of business-readable scenarios.
- Not running acceptance tests against a production-like environment — passing on dev, failing on prod.
- Flaky acceptance tests that are sometimes ignored — a test suite that is sometimes ignored provides no safety net.
Avoid When
- Testing low-level logic that can be covered by unit or integration tests.
- Verifying UI implementation details like CSS, HTML attributes, or layout.
- Running on every small code change where faster test layers provide sufficient coverage.
When To Use
- Validating critical user journeys like checkout, authentication, and payment flows.
- Ensuring business requirements are correctly implemented before release.
- Creating shared understanding between developers, QA, and non-technical stakeholders.
Code Examples
// Acceptance test that's too granular — should be a unit test:
// Test: verify that the password field has a 'required' attribute
// This is a unit/integration concern, not an acceptance concern
// Acceptance test should be: 'User cannot log in without providing a password'
// — the business requirement, not the HTML implementation detail# Behat feature file — written in Gherkin, readable by stakeholders
Feature: User login
Scenario: Successful login
Given I am on "/login"
When I fill in "email" with "user@example.com"
And I fill in "password" with "secret"
And I press "Log in"
Then I should see "Welcome back"
And I should be on "/dashboard"
Scenario: Invalid credentials
Given I am on "/login"
When I fill in "email" with "wrong@example.com"
And I fill in "password" with "wrong"
And I press "Log in"
Then I should see "Invalid credentials"