Layered Test Architecture for Growing Products

This post is the first part of the Test Architecture series. We’ll explore how to build test suites that scale with your product, avoid redundancy, and provide fast, reliable feedback.

Introduction — Why Layer Matters

When your product is small, test architecture doesn’t matter much. You write tests where it feels natural, run them when you remember, and ship when things seem okay. The feedback loop is fast because the codebase is small.

Then the product grows. The team grows. More features. More integrations. More edge cases. The test suite that felt lightweight and useful now takes 40 minutes to run, fails unpredictably, and nobody is quite sure what each test actually validates.

This is where layered test architecture becomes critical.

A layered test architecture organises tests by the system boundary they operate at: unit, API, and UI. Each layer has a distinct purpose, speed, and failure signal. Tests are deliberately placed in the layer where they provide maximum value at minimum cost.

Without this structure, teams drift toward one of two failure modes:

Over-reliance on UI tests — slow, brittle, expensive to maintain
Over-reliance on unit tests — fast but missing integration gaps

Both extremes create blind spots. Layered architecture solves this by distributing responsibility across layers based on what each layer does best.

The Three Layers

Unit Layer — Logic and Behaviour in Isolation

Purpose: Test individual functions, classes, or modules in isolation. Validate business logic, edge cases, and error handling without involving external dependencies.

Characteristics:

Fast — milliseconds per test
Focused — tests one behaviour at a time
Isolated — no database, no network, no file system

What to test here:

Business logic: calculations, validation rules, state transitions
Edge cases: null inputs, boundary conditions, invalid data
Error handling: exceptions, retries, fallback logic

Example (TypeScript):

// Unit test for a pricing calculator
describe('calculateDiscountedPrice', () => {
  it('applies 10% discount when total exceeds $100', () => {
    expect(calculateDiscountedPrice(120)).toBe(108);
  });

  it('throws error for negative amounts', () => {
    expect(() => calculateDiscountedPrice(-10)).toThrow('Invalid amount');
  });
});

:::tip[Unit Test Ownership] Unit tests are owned by developers. They run before commit, in the IDE, as part of the dev workflow. If a unit test fails, the developer fixes it before pushing code. :::

API Layer — Integration Without UI

Purpose: Test the interaction between components through the API layer. Validate request handling, database operations, authentication, and business workflows without involving the UI.

Characteristics:

Moderate speed — seconds per test
Real integrations — actual database, real auth, real services (or realistic mocks)
Independent of UI — tests survive UI redesigns

What to test here:

Request validation and error responses
Database transactions and data integrity
Authentication and authorization rules
Multi-step workflows (e.g., create account → verify email → login)

Example (Playwright API testing):

test('POST /orders validates required fields', async ({ request }) => {
  const response = await request.post('/api/orders', {
    data: { productId: 123 } // missing quantity
  });
  
  expect(response.status()).toBe(400);
  const body = await response.json();
  expect(body.errors).toContain('quantity is required');
});

:::info[API Tests Are the Sweet Spot] API tests provide strong integration coverage at a fraction of the cost of UI tests. They catch configuration issues, database problems, and integration failures that unit tests miss — without the brittleness of UI automation. :::

UI Layer — User Journeys and Visual Contracts

Purpose: Test the complete user experience through the browser. Validate that critical user journeys work end-to-end and that the UI behaves correctly in real-world scenarios.

Characteristics:

Slow — seconds to minutes per test
Brittle — sensitive to UI changes, timing issues, browser differences
Comprehensive — exercises the full stack

What to test here:

Critical user journeys (signup, checkout, payment)
UI-specific behaviour (modals, drag-and-drop, responsive layout)
Visual regressions (screenshot comparison)
Accessibility (keyboard navigation, screen reader compatibility)

What NOT to test here:

Edge cases already covered by unit tests
Validation logic already covered by API tests
Every possible UI state (combinatorial explosion)

Example (Playwright UI test):

test('user can complete checkout flow', async ({ page }) => {
  await page.goto('/cart');
  await page.click('text=Proceed to checkout');
  await page.fill('#email', 'customer@example.com');
  await page.fill('#cardNumber', '4242424242424242');
  await page.click('text=Place order');
  
  await expect(page.locator('text=Order confirmed')).toBeVisible();
});

:::warning[UI Tests Are Expensive] UI tests are the most expensive to write, run, and maintain. Only write UI tests for workflows that genuinely need end-to-end validation. If the same behaviour can be tested at the API or unit layer, test it there instead. :::

Avoiding Duplicate Coverage

The most common mistake in layered test architecture is testing the same thing at multiple layers.

Example: Password Validation

Wrong approach — testing validation at all three layers:

Unit test: validates password length, character requirements
API test: sends invalid passwords and checks 400 responses
UI test: types invalid passwords and checks error messages

Right approach — test once at the appropriate layer:

Unit test: comprehensive validation logic (length, characters, complexity)
API test: one smoke test confirming validation is called
UI test: one smoke test confirming error message displays correctly

The Principle: Test at the Lowest Layer That Provides Confidence

If a unit test proves the validation logic works, you don’t need 50 API tests trying every edge case. The API test just confirms the unit is wired up correctly. The UI test just confirms the error message renders.

Benefits:

Faster test suite (fewer slow tests)
Lower maintenance cost (one place to update when logic changes)
Clearer failure signals (failure location = layer of actual problem)

Ownership Per Layer

Each layer should have clear ownership — someone responsible for maintaining that layer, fixing failures, and ensuring the tests remain valuable.

Layer	Primary Owner	Runs When	Purpose
Unit	Developers	Pre-commit, on save	Fast feedback on logic changes
API	QA Engineers or Developers	PR pipeline	Integration confidence
UI	QA Engineers	Nightly or pre-release	End-to-end journey validation

:::tip[Shared Ownership for API Tests] API tests sit at the boundary between dev and QA. Some teams have developers write API tests for new endpoints, then QA extends them with additional scenarios. This works well because API tests are code — they benefit from code review and dev tooling. :::

Ports Between Layers — The Dependency Rule

A well-designed test architecture respects layer boundaries. Tests at a higher layer should not bypass or directly access logic from a lower layer.

Example:

A UI test should not mock API responses at the network layer (use a real API)
An API test should not directly invoke database queries (use the API endpoint)

Why? Because bypassing layers defeats the purpose of integration testing. If your API test mocks the database, you’re not testing the integration between the API and the database — you’re testing a fantasy version of your system that doesn’t exist in production.

Exception: Mocking external services (payment gateways, third-party APIs) is acceptable and often necessary to keep tests deterministic and fast.

Practical Example — E-commerce Checkout

Let’s apply layered architecture to an e-commerce checkout feature.

Unit Layer

Price calculation with tax and discounts
Inventory availability check logic
Payment validation rules

API Layer

POST /cart/add — adds item, updates inventory
POST /checkout — validates cart, processes payment, creates order
GET /orders/:id — retrieves order confirmation

UI Layer

One critical path test: Add item to cart → proceed to checkout → enter payment details → confirm order → see confirmation page

Notice: the UI layer has one test. The validation logic, inventory checks, and payment rules are already proven at lower layers. The UI test just confirms the happy path works end-to-end in a browser.

Conclusion

Layered test architecture is not about writing more tests — it’s about writing the right tests in the right places. Each layer has a purpose:

Unit tests prove logic correctness
API tests prove integration reliability
UI tests prove user journeys work end-to-end

Avoid duplication. Test at the lowest layer that gives you confidence. Assign clear ownership. Respect layer boundaries.

This structure scales. As your product grows, you add tests to the appropriate layer without bloating the slow, brittle top layer.

:::tip[Start Small] If you’re introducing layered architecture to an existing project, start with one feature. Refactor its tests into unit, API, and UI layers. Measure the speed improvement and maintenance reduction. Then expand. :::

Action for this week: Pick one feature you’ve tested. Map out which tests could move to a lower layer. Identify duplicate coverage. Refactor one test suite to follow the layered model and measure the time saved.

Next in the series: Part 2 — Test Environments Without Shared Chaos, where we’ll tackle test environment isolation, data seeding, and how to avoid the “someone broke staging” problem.