Note: BDR (Behavior-Driven Living Requirements) is my own architectural approach to organizing Playwright tests — a Cucumber-free alternative to BDD that I designed and documented at bdr-methodology.dev.

Monday morning. Coffee. You open GitLab — and CI is red. Classic.

You open the report. There's a wall of text, five screens long. Somewhere in there: TimeoutError on a click. The selector looks fine — data-testid="checkout-submit". But why did it fail? Was the database down? Did the frontend not render the button? Did some API return an unexpected response?

To find out, you have to dive into the test code and debug it line by line. Mentally reconstruct what the app state was. Read through fifty lines of setup just to understand what was being tested.

This is the real cost of unreadable test reports. Not the failure itself — but the hour you spend just figuring out what failed and why.

The classic POM: looks clean, reports terribly

Most teams start here. You write a clean Page Object:

import { Page } from '@playwright/test';

export class CartPage {
  constructor(private readonly page: Page) {}

  async clickCheckout() {
    await this.page.getByTestId('checkout-submit').click();
  }
}

The code looks great. Clean, atomic, no logic in the wrong place.

But the report? It looks like this:

✓ Test: User can complete purchase
  - clickCheckout
  - fillDetails
  - submit

How do you understand the context from that in five seconds? You can't. The developer opens the test code, reads through it, swears, mentally reconstructs what was happening. Time gone.

"Just use test.step everywhere" — don't do this

Someone will suggest: "Just wrap everything in test.step, what's the problem?"

Don't. It works for three tests. At a hundred, it kills the project.

Copy-paste will destroy you. The login → cart → checkout chain ends up in most test files. Login logic changes? Congratulations, you're editing fifty files by hand.

Maintenance becomes a nightmare. Checkout now requires a "agree to terms" checkbox? Go insert await page.click(...) in a hundred places.

Tests lose their meaning. A ten-line test balloons to fifty lines of await test.step(...) noise. The actual business intent disappears behind the boilerplate.

The fix: a Flow layer between POM and tests

The solution is a layer between "dumb" pages and tests. But here's the key insight most teams miss: a Flow is not just a reusable helper. It's a business entity.

Think of an e-commerce app. You have three distinct business actions:

• Adding a product to the cart — a self-contained business event
• Placing an order — another self-contained business event
• Processing payment — yet another

Each of these deserves its own Flow class. Not because of DRY (though that's a nice side effect), but because each one represents a real business concept with its own rules and responsibilities.

Then your Spec just assembles them like Lego:

// Scenario 1: full happy path
await cart.addProduct(laptop);
await checkout.placeOrder(address);
await payment.pay(card);

// Scenario 2: just verify cart behaviour
await cart.addProduct(laptop);
await cart.verifyTotal(1200);

Same building blocks, different scenarios. The Spec doesn't care how "add product" works internally — it just uses the business entity.

This distinction has a real consequence. If the business process for checkout changes from one screen to three, your test remains the same:

await checkoutFlow.completePurchase(orderData);

You change the implementation inside the Flow, but the test — the business intent — stays untouched. That's the difference between a brittle script and a resilient test framework.

A Flow is a conductor — it knows nothing about selectors or clicks. It only knows about the business process.

export class CheckoutFlow {
  constructor(
    private cartPage: CartPage,
    private paymentPage: PaymentPage,
  ) {}

  async completePurchase(orderData: OrderData) {
    await test.step('WHEN: User proceeds to checkout', async () => {
      await this.cartPage.clickCheckout();
      await expect(this.paymentPage.form).toBeVisible();
    });

    await test.step('WHEN: User fills payment details', async () => {
      await this.paymentPage.fillDetails(orderData.card);
      await this.paymentPage.submit();
    });
  }
}

Now the report looks like this:

✓ Test: User can complete purchase
  ✓ WHEN: User proceeds to checkout
  ✓ WHEN: User fills payment details
  ✓ THEN: Order confirmation is displayed

Test failed? The developer opens the report. Thirty seconds — and they know exactly which business step broke. No code diving required.

Why three layers — and what breaks if you skip one

This is the part most teams skip. They add a Flow layer but let the boundaries blur. A month later, everything is tangled again.

Here's why each layer exists and what happens when you violate it:

POM knows about selectors. Nothing else.
If your POM starts containing business logic — "click checkout AND verify the payment page appeared" — you've coupled UI structure to business rules. Change the UI, and your business logic breaks with it.

Flow knows about business processes. Nothing about selectors.
If your Flow starts calling page.getByTestId(...) directly, you've lost the separation that makes refactoring safe. Now a selector change requires touching both the POM and the Flow.

Spec knows about intent. Nothing about implementation.
Your test should read like a user story. If it's full of .fill() and .click() calls, a non-engineer can't read it — and you've lost the "living documentation" value entirely.

The rule: each layer talks only to the layer directly below it. Spec → Flow → POM. Never skip a level.

What the report becomes

With this architecture, your Allure report stops being a log of browser actions and becomes a record of business events.

When a test fails, the report answers three questions immediately:

• What was being tested (the test name)
• Where it broke (the step name)
• What the state was (attached tables with data)

That's the difference between a report that developers ignore and one they actually use.

Try it

This architecture is the foundation of BDR — Behavior-Driven Living Requirements.

• BDR Methodology — full architecture docs
• Playwright BDR Template — working implementation to clone

I'm open to QA Automation roles — remote, contract, or full-time.
dmitryAQA@outlook.com | @DmitryMeAQA