Criterion: "User can filter products by category"
├─ Happy path: Select category, products filter correctly
├─ Edge case: No products match filter, show empty state
├─ Edge case: Clear filter, all products show again
├─ Error case: Filter API fails, show error message
└─ Accessibility: Filter controls are keyboard accessible

Function: filterProducts(products, category)
├─ Acceptance: Returns matching products (from criteria)
├─ Implementation: Returns empty array when products is null
├─ Implementation: Returns all products when category is empty string
├─ Implementation: Handles case-insensitive category matching
└─ Implementation: Does not mutate original array

describe("calculateDiscount", () => {
  describe("when customer has premium membership", () => {
    it("applies 20% discount to order total", () => {
      // Arrange - Set up test data matching criterion
      const order = { total: 100, membership: "premium" };
      
      // Act - Call the function
      const result = calculateDiscount(order);
      
      // Assert - Verify expected outcome from requirements
      expect(result).toBe(80);
    });
  });
});

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

describe("LoginForm", () => {
  describe("when credentials are invalid", () => {
    it("displays error message to user", async () => {
      const user = userEvent.setup();
      render(<LoginForm />);
      
      // Interact using accessible queries
      await user.type(
        screen.getByLabelText(/email/i),
        "invalid@test.com"
      );
      await user.type(
        screen.getByLabelText(/password/i),
        "wrong"
      );
      await user.click(
        screen.getByRole("button", { name: /sign in/i })
      );
      
      // Assert on user-visible outcome
      expect(
        await screen.findByRole("alert")
      ).toHaveTextContent(/invalid credentials/i);
    });
  });
});

import { test, expect } from "@playwright/test";

test.describe("Product Catalog", () => {
  test.describe("filtering by category", () => {
    test("shows only matching products", async ({ page }) => {
      await page.goto("/products");
      
      // Use semantic locators
      await page.getByRole("combobox", { name: /category/i }).selectOption("Electronics");
      
      // Assert count, then spot-check first/last
      const products = page.getByRole("article");
      await expect(products).toHaveCount(5);
      await expect(products.first()).toContainText(/electronics/i);
      await expect(products.last()).toContainText(/electronics/i);
    });
  });
});

test("all products match filter", async ({ page }) => {
  await page.goto("/products");
  await page.getByRole("combobox", { name: /category/i }).selectOption("Electronics");
  
  const products = await page.getByRole("article").all();
  
  // Parallel assertions — faster than sequential await in a loop
  await Promise.all(
    products.map(product =>
      expect(product.getByText(/electronics/i)).toBeVisible()
    )
  );
});

test.describe("Login Page", () => {
  test("has correct form structure", async ({ page }) => {
    await page.goto("/login");
    
    // One snapshot replaces 5+ individual assertions
    await expect(page.getByRole("main")).toMatchAriaSnapshot(`
      - heading "Sign In" [level=1]
      - textbox "Email"
      - textbox "Password"
      - button "Sign In"
      - link "Forgot password?"
    `);
  });
  
  test("shows validation errors on empty submit", async ({ page }) => {
    await page.goto("/login");
    await page.getByRole("button", { name: /sign in/i }).click();
    
    await expect(page.getByRole("form")).toMatchAriaSnapshot(`
      - textbox "Email"
      - text "Email is required"
      - textbox "Password"
      - text "Password is required"
      - button "Sign In"
    `);
  });
});

// BAD: Tests internal method exists, provides no behavior guarantee
it("has a validateFields method", () => {
  expect(form.#validateFields).toBeDefined();
});

// BAD: Asserts implementation without verifying outcome
it("calls the validator", () => {
  expect(mockValidator).toHaveBeenCalledWith(data);
});

// GOOD: Tests observable behavior (acceptance)
it("prevents submission with invalid email", async () => {
  await user.type(emailInput, "not-an-email");
  await user.click(submitButton);
  expect(screen.getByRole("alert")).toHaveTextContent(/valid email/i);
});

// ALSO GOOD: Tests implementation robustness (unit)
it("returns validation errors for malformed email", () => {
  const result = validateEmail("not-an-email");
  expect(result.valid).toBe(false);
  expect(result.error).toBe("Invalid email format");
});

// BAD: Test data derived from implementation
const expected = formatPrice(100); // Don't compute expected from code!
expect(formatPrice(100)).toBe(expected);

// GOOD: Expected value from requirements
expect(formatPrice(100)).toBe("$100.00");

// BAD: Mock everything, test nothing real
jest.mock("./api");
jest.mock("./utils");
jest.mock("./formatter");
// Now just testing mocks talk to each other

// GOOD: Mock only external boundaries
// Mock: APIs, databases, time, file system
// Real: Business logic, components, formatters

// BAD: Implementation-dependent selectors
page.locator(".btn-primary.submit-form");
page.locator("#root > div > form > button:nth-child(3)");

// GOOD: Semantic locators
page.getByRole("button", { name: /submit order/i });