Appearance

Acceptance Testing ​

Black-box testing that validates system behavior from the outside in

Related Concepts: Clean Architecture | Dependency Inversion | Frontend Testing | Backend Integration Testing

Table of Contents ​

  1. What Are Acceptance Tests?
  2. Why Acceptance Tests Matter
  3. The Layered Architecture
  4. BDD and ATDD at Synapse
  5. API vs End-to-End Tests
  6. The Arrangement Pattern
  7. Test Independence
  8. Best Practices
  9. Summary

What Are Acceptance Tests? ​

Black-Box Testing from the Outside In ​

Acceptance tests validate system behavior from the perspective of the system itself—not individual components or units. They are black-box tests that verify the system does what it's supposed to do without knowing or caring how it accomplishes that internally.

At Synapse, acceptance tests focus on specific interactions rather than complete user journeys. We test that:

  • A specific API endpoint correctly processes a payment
  • A particular form submission triggers the right workflow
  • A certain button click produces the expected outcome

These are discrete, testable behaviors—not sprawling scenarios that traverse the entire application.

Executable Specifications ​

Acceptance tests serve as living documentation. Each test is an executable specification that:

  • Defines expected behavior in business terms
  • Validates that behavior automatically
  • Provides clear examples of system usage
  • Remains current as the system evolves

Even when we're not using Gherkin syntax, our tests read as specifications. They're declarative, hiding implementation details and speaking only in domain and behavioral terms.

Position in the Test Pyramid ​

Acceptance tests sit at the tip of the testing pyramid:

         /\
        /  \  Acceptance Tests (< 10%)
       /    \  - Most expensive to write, run, maintain
      /──────\  - Highest confidence per test
     /        \  - Critical business behaviors only
    /          \
   / Integration \ Integration Tests (20%)
  /    Tests     \ - Component interactions
 /────────────────\ - Technical validation
/                  \
    Unit Tests      Unit Tests (70%)
──────────────────  - Fast, focused, numerous

This positioning is deliberate. Acceptance tests are expensive—they take longer to write, run slower, and require more maintenance. We use them sparingly, focusing on the most critical behaviors that justify the cost.

Why Acceptance Tests Matter ​

Business Confidence ​

Acceptance tests provide the ultimate confidence: the system works from the outside. While unit tests verify algorithms and integration tests confirm components interact correctly, acceptance tests prove the system delivers business value.

This confidence is essential for:

  • Deployment decisions
  • Contract validation
  • Regression prevention
  • Stakeholder communication

Contract Verification ​

Modern systems expose contracts through APIs and interfaces. Acceptance tests verify these contracts remain stable as internal implementation evolves. They ensure:

  • API responses match documented schemas
  • Error codes and messages remain consistent
  • Breaking changes are detected before deployment

Living Documentation ​

Unlike traditional documentation that grows stale, acceptance tests are executed continuously. They provide:

  • Current examples of system behavior
  • Clear specifications of business rules
  • Concrete scenarios for onboarding
  • Validation that documentation matches reality

The Layered Architecture ​

Separation of Concerns ​

Acceptance tests follow a strict layered architecture that separates test intent from implementation details:

┌─────────────────────────────────────────┐
│         Test Specification Layer        │
│                                         │
│  "Payment processing handles declines"  │
│  "Inventory updates after purchase"     │
│  - Pure business language               │
│  - No technical details                 │
│  - Declarative intent only              │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│           Driver Layer                  │
│                                         │
│  Workflows    Page Objects   API        │
│  Builders     Test Clients   Helpers    │
│  - Technical abstraction                │
│  - Reusable components                  │
│  - Hides complexity                     │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│        Infrastructure Layer             │
│                                         │
│  HTTP       Database    Browser         │
│  Network    Fixtures    Config          │
│  - Environment management               │
│  - Resource allocation                  │
│  - Technical implementation             │
└─────────────────────────────────────────┘

Why Layered Architecture Matters ​

This separation provides crucial benefits:

Maintainability: When the UI changes, only the driver layer needs updating. The test specifications remain unchanged because the business behavior hasn't changed.

Readability: Tests read like requirements documents. Non-technical stakeholders can understand what's being tested without getting lost in implementation details.

Reusability: Driver components are shared across tests. A PaymentWorkflow helper might be used by dozens of tests, ensuring consistency and reducing duplication.

Stability: Tests are insulated from technical changes. Whether you're using REST, GraphQL, or gRPC, the test specifications remain the same.

The Driver Pattern in Practice ​

The driver pattern creates stable interfaces between test specifications and system implementation. Instead of tests knowing about HTTP requests, CSS selectors, or database schemas, they interact through domain-specific abstractions.

Consider testing payment processing:

  • The test specification says "process payment with invalid card"
  • The driver layer knows how to submit payments (API calls, form fields, etc.)
  • The infrastructure layer handles HTTP requests, authentication tokens, and response parsing

This separation means that when you switch from REST to GraphQL, only the driver layer changes. When you redesign the payment form, only the page object updates. The test specification—the actual business requirement—remains untouched.

BDD and ATDD at Synapse ​

Behavior-Driven Development ​

We leverage BDD principles for defining and implementing acceptance tests. This means:

  • Tests are written from the perspective of system behavior
  • Business language takes precedence over technical terminology
  • Scenarios focus on outcomes, not processes
  • Tests serve as shared understanding between development and business

Acceptance Test-Driven Development ​

ATDD guides our implementation process:

  1. Define acceptance criteria before implementation
  2. Write acceptance tests that verify those criteria
  3. Implement features to make tests pass
  4. Refactor while keeping tests green

This approach ensures we build exactly what's needed—no more, no less.

Declarative Testing ​

Our acceptance tests are declarative, expressing what should happen, not how it happens. This distinction is critical:

Imperative (avoid): Click button X, fill field Y, wait for element Z Declarative (prefer): Process payment, verify transaction completed

Declarative tests remain stable as implementation evolves. They express business intent without coupling to technical details.

API vs End-to-End Tests ​

The 90/10 Rule ​

At Synapse, approximately 90% of acceptance tests should be API tests, with only 10% being true end-to-end tests through the UI. This ratio is intentional and based on practical experience.

Why API Tests Dominate ​

API tests provide most of the value with less cost:

Speed: API tests run in seconds, not minutes. No browser startup, no page loads, no waiting for animations.

Stability: APIs change less frequently than UIs. Tests break less often and require less maintenance.

Precision: API tests can verify exact response codes, headers, and payloads. UI tests struggle with precise validation.

Coverage: Most business logic lives in the backend. API tests validate system behavior directly.

When to Use E2E Tests ​

Reserve end-to-end tests for hand-picked high value scenarios

  • Critical user flows that must work (checkout, registration)
  • Visual regression testing
  • Cross-browser compatibility verification
  • Client-side business logic validation
  • Integration between multiple frontend components

E2E tests are expensive. Use them sparingly for maximum value.

The Cost Multiplier ​

Consider the relative costs:

  • Writing: E2E tests take 3-5x longer to write than API tests
  • Running: E2E tests run 10-50x slower than API tests
  • Maintaining: E2E tests break 5-10x more often than API tests
  • Debugging: E2E test failures take 3-5x longer to diagnose

These multipliers compound. A test suite heavy on E2E tests becomes a burden that slows development rather than enabling it.

The Arrangement Pattern ​

Never Use the UI for Setup ​

A critical principle borrowed from backend integration testing: never use the UI to arrange test data. This principle is even more important for acceptance tests because:

  • UI setup is extremely slow
  • UI changes break test setup even when the test itself is fine
  • Complex setup through UI is error-prone
  • UI setup obscures what data actually exists

Use APIs for Test Arrangement ​

Always arrange test data through APIs:

  1. Create users via user management API
  2. Set up products via catalog API
  3. Configure settings via configuration API
  4. Establish state via appropriate service APIs

Only use the UI for the action being tested and assertions about UI state.

Why This Matters ​

Consider testing "user can edit their profile":

Poor approach:

  1. Navigate to registration page (UI)
  2. Fill out registration form (UI)
  3. Submit registration (UI)
  4. Navigate to profile page (UI)
  5. Edit profile (UI) ← The actual test
  6. Verify changes (UI)

Better approach:

  1. Create user via API
  2. Navigate directly to profile page (UI)
  3. Edit profile (UI) ← The actual test
  4. Verify changes (UI and/or API)

The better approach is faster, more stable, and clearer about what's actually being tested.

Benefits of API Arrangement ​

  • Speed: API calls complete in milliseconds, not seconds
  • Reliability: APIs are more stable than UI
  • Clarity: Test data is explicit and programmatic
  • Maintenance: Changes to UI don't break test setup
  • Focus: Tests clearly show what behavior they're validating

Test Independence ​

Complete Isolation ​

Every acceptance test must be completely independent:

  • No shared state between tests
  • No dependency on execution order
  • No reliance on previous test results
  • No cleanup dependencies

This independence is non-negotiable. It enables:

  • Parallel execution for speed
  • Reliable results regardless of execution order
  • Clear failure diagnosis
  • Confident test selection and filtering

Achieving Independence ​

Test independence requires discipline:

Unique test data: Each test creates its own users, products, orders. Use timestamps or UUIDs to ensure uniqueness.

Direct navigation: Tests navigate directly to the relevant page/endpoint, not through a series of clicks from the homepage.

State verification: Tests verify initial state before acting, ensuring preconditions are met.

Isolation mechanisms: Use separate database schemas, API namespaces, or tenant IDs for parallel execution.

The Cost of Dependencies ​

Test dependencies create cascading problems:

  • One failure causes multiple test failures
  • Debugging becomes detective work
  • Parallel execution becomes impossible
  • Test execution time increases linearly
  • Maintenance burden grows exponentially

Independent tests avoid these problems entirely.

Best Practices ​

DO ✅ ​

Test Design ​

  • Focus on specific interactions rather than long user journeys
  • Write tests as executable specifications using business language
  • Maintain strict layer separation between specification, driver, and infrastructure
  • Use the 90/10 rule for API vs E2E test distribution
  • Arrange via API, act via UI when testing UI behaviors

Implementation ​

  • Keep tests independent with no shared state or dependencies
  • Use declarative expressions that hide implementation details
  • Create reusable driver components for common operations
  • Verify both happy and unhappy paths including error scenarios
  • Make tests deterministic with controlled time, data, and randomness

Maintenance ​

  • Fix flaky tests immediately or remove them
  • Update driver layer first when implementation changes
  • Keep test data minimal to reduce complexity and runtime
  • Version test contracts to handle API evolution
  • Monitor test metrics including runtime, flakiness, and failure rates

DON'T ❌ ​

Test Design ​

  • Don't test implementation details - focus on observable behavior
  • Don't create test dependencies - each test stands alone
  • Don't over-specify - allow implementation flexibility
  • Don't test the framework - trust external code
  • Don't use UI for test setup - use APIs instead

Implementation ​

  • Don't hard-code test data - use builders and factories
  • Don't use CSS selectors in tests - hide them in page objects
  • Don't skip error scenarios - negative tests prevent bugs
  • Don't use fixed delays - use proper wait conditions
  • Don't share test accounts - create unique data per test

Maintenance ​

  • Don't let tests rot - remove or fix failing tests
  • Don't test everything at E2E level - respect the test pyramid
  • Don't duplicate driver code - extract and reuse
  • Don't ignore performance - slow tests get skipped
  • Don't commit secrets - use secure configuration

Summary ​

Acceptance tests at Synapse validate system behavior from the outside in. They are:

  • Black-box tests that verify behavior without knowing implementation
  • Executable specifications written in business language
  • Expensive but valuable providing ultimate confidence in system behavior

Key principles:

  1. Layered architecture separates concerns and enables maintenance
  2. 90% API, 10% E2E optimizes for value versus cost
  3. API arrangement keeps tests fast and focused
  4. Complete independence enables reliable parallel execution
  5. Declarative specifications hide complexity and improve readability

Remember: acceptance tests are the tip of the pyramid. Use them sparingly for critical behaviors that justify their cost. Most testing should happen at the unit and integration levels, with acceptance tests providing final validation that the system delivers business value.

The goal isn't to test everything at the acceptance level—it's to test the right things at the right level. When you get this balance right, acceptance tests become a powerful tool for ensuring system quality without becoming a maintenance burden.

For implementation specifics, see our acceptance testing implementation guide. For component-level testing with real dependencies, see our Backend Integration Testing guide.