Test Organization

import { test, expect } from "@playwright/test";
// => Import Playwright test runner and assertion library
// => @playwright/test provides test() and expect() functions
// => No additional frameworks required

test("user can login", async ({ page }) => {
  // => test() registers test case with runner
  // => async function receives page fixture
  // => page fixture provides browser context

  await page.goto("https://example.com/login");
  // => Navigate to login page
  // => await waits for page load
  // => page.goto() returns Promise<Response>

  await page.fill("#username", "testuser");
  // => Fill username input by CSS selector
  // => #username targets element with id="username"
  // => await waits for element to be actionable

  await page.fill("#password", "testpass123");
  // => Fill password input
  // => Selectors directly embedded in test

  await page.click('button[type="submit"]');
  // => Click submit button by attribute selector
  // => Waits for button to be visible and enabled
  // => Triggers form submission

  await expect(page.locator(".welcome-message")).toBeVisible();
  // => Assert welcome message appears
  // => .welcome-message targets element by class
  // => toBeVisible() waits up to 5 seconds (default timeout)
});

test("user can logout", async ({ page }) => {
  // => Second test case
  // => Separate test function, new page fixture
  // => No shared state between tests

  await page.goto("https://example.com/dashboard");
  // => Navigate to dashboard
  // => Duplicates login flow (not shown)
  // => Must login first to access dashboard

  await page.click("#logout-button");
  // => Click logout button by ID
  // => Direct selector in test code
  // => Changes to button ID require test updates

  await expect(page).toHaveURL("https://example.com/login");
  // => Assert redirected to login page
  // => Verifies logout successful
  // => toHaveURL() checks current page URL
});

test("user updates profile", async ({ page }) => {
  // => Third test requiring login
  // => Must duplicate login logic again
  // => Selectors repeated across test suite

  await page.goto("https://example.com/login");
  await page.fill("#username", "testuser");
  // => Same selectors as first test
  await page.fill("#password", "testpass123");
  // => Duplication increases maintenance burden
  await page.click('button[type="submit"]');
  // => If selector changes, all tests break

  await page.goto("https://example.com/profile");
  // => Navigate to profile page after login

  await page.fill("#email", "newemail@example.com");
  // => Update email field
  // => Direct selector in test

  await page.click('button:has-text("Save")');
  // => Click Save button by text content
  // => Text-based selector fragile to UI copy changes

  await expect(page.locator(".success-toast")).toBeVisible();
  // => Assert success notification
  // => .success-toast selector embedded in test
});

npm install --save-dev @playwright/test
# => Playwright test runner includes POM support
# => No additional dependencies needed
# => Fixtures built into @playwright/test

// pages/LoginPage.ts
import { Page, Locator } from "@playwright/test";
// => Import Playwright types for page and elements
// => Page represents browser page/tab
// => Locator represents element reference

export class LoginPage {
  // => Export class for reuse across tests
  // => Encapsulates login page interactions
  // => Single source of truth for login selectors

  readonly page: Page;
  // => Page reference passed from test
  // => readonly prevents accidental reassignment
  // => Used for navigation and context

  readonly usernameInput: Locator;
  // => Locator for username input field
  // => Lazily evaluated (selector resolved on use)
  // => Cached for reuse within test

  readonly passwordInput: Locator;
  // => Password input locator
  // => readonly ensures selector stability

  readonly submitButton: Locator;
  // => Submit button locator
  // => Centralized selector definition

  readonly welcomeMessage: Locator;
  // => Welcome message after successful login
  // => Used for login verification

  constructor(page: Page) {
    // => Constructor receives page from test
    // => Initializes all locators
    // => Page object tied to specific page instance

    this.page = page;
    // => Store page reference
    // => Used by navigation methods

    this.usernameInput = page.locator("#username");
    // => Define username selector once
    // => All tests use same selector
    // => Changes require single update

    this.passwordInput = page.locator("#password");
    // => Password field selector
    // => Encapsulated in page object

    this.submitButton = page.locator('button[type="submit"]');
    // => Submit button selector
    // => Isolated from test code

    this.welcomeMessage = page.locator(".welcome-message");
    // => Welcome message selector
    // => Used for assertions
  }

  async goto() {
    // => Navigation method
    // => Encapsulates login page URL
    // => Returns Promise for await

    await this.page.goto("https://example.com/login");
    // => Navigate to login page
    // => URL centralized in page object
    // => Changes require single update
  }

  async login(username: string, password: string) {
    // => High-level login method
    // => Encapsulates multi-step interaction
    // => Reusable across all tests

    await this.usernameInput.fill(username);
    // => Fill username input
    // => Uses centralized locator
    // => Waits for element automatically

    await this.passwordInput.fill(password);
    // => Fill password input
    // => Type-safe parameter

    await this.submitButton.click();
    // => Click submit button
    // => Triggers form submission
    // => Waits for navigation automatically
  }

  async expectWelcomeMessage() {
    // => Assertion helper method
    // => Encapsulates verification logic
    // => Returns Promise for await

    await expect(this.welcomeMessage).toBeVisible();
    // => Assert welcome message visible
    // => Uses centralized locator
    // => Waits up to timeout
  }
}

// tests/auth.spec.ts
import { test, expect } from "@playwright/test";
import { LoginPage } from "../pages/LoginPage";
// => Import LoginPage page object
// => Encapsulates login interactions
// => Reusable across test files

test("user can login", async ({ page }) => {
  // => Test receives page fixture
  // => Pass page to page object constructor
  // => Cleaner test code

  const loginPage = new LoginPage(page);
  // => Create page object instance
  // => Pass page fixture to constructor
  // => loginPage provides high-level methods

  await loginPage.goto();
  // => Navigate to login page
  // => URL encapsulated in page object
  // => No hardcoded URLs in test

  await loginPage.login("testuser", "testpass123");
  // => Perform login interaction
  // => Single method call replaces 3 steps
  // => Reusable login logic

  await loginPage.expectWelcomeMessage();
  // => Verify login successful
  // => Assertion encapsulated in page object
  // => Clear test intent
});

test("user can logout", async ({ page }) => {
  // => Second test using page objects
  // => Reuses LoginPage for setup
  // => Cleaner than duplicating selectors

  const loginPage = new LoginPage(page);
  await loginPage.goto();
  await loginPage.login("testuser", "testpass123");
  // => Reuse login logic
  // => No selector duplication
  // => If login UI changes, update LoginPage once

  const dashboardPage = new DashboardPage(page);
  // => Create dashboard page object
  // => Encapsulates dashboard interactions
  // => Similar pattern to LoginPage

  await dashboardPage.logout();
  // => Logout method encapsulated in page object
  // => Single responsibility per page

  await expect(page).toHaveURL("https://example.com/login");
  // => Verify redirect to login page
  // => URL check remains in test (business logic)
});

// fixtures/authFixture.ts
import { test as base } from "@playwright/test";
import { LoginPage } from "../pages/LoginPage";
// => Import base test from Playwright
// => Extend with custom fixtures
// => Dependency injection pattern

type AuthFixtures = {
  authenticatedPage: Page;
  // => Custom fixture providing logged-in state
  // => Tests receive authenticated page
  // => Eliminates login duplication
};

export const test = base.extend<AuthFixtures>({
  // => Extend base test with custom fixtures
  // => Type-safe fixture definitions
  // => Compose fixtures for complex setups

  authenticatedPage: async ({ page }, use) => {
    // => Define authenticatedPage fixture
    // => Receives page fixture as dependency
    // => use() callback provides fixture value

    const loginPage = new LoginPage(page);
    // => Create login page object
    // => Use page fixture from context

    await loginPage.goto();
    await loginPage.login("testuser", "testpass123");
    // => Perform login before test runs
    // => Setup code runs once per test
    // => Automatic cleanup after test

    await use(page);
    // => Provide authenticated page to test
    // => Test receives logged-in state
    // => await use() pauses until test completes

    // Cleanup code runs here after test
    // => Automatic teardown
    // => Logout, clear cookies, etc.
  },
});

// tests/dashboard.spec.ts
import { test } from "../fixtures/authFixture";
import { expect } from "@playwright/test";
// => Import custom test with auth fixture
// => Tests automatically start authenticated
// => No manual login required

test("user sees dashboard content", async ({ authenticatedPage }) => {
  // => Test receives authenticated page
  // => Already logged in
  // => No setup code needed

  await authenticatedPage.goto("https://example.com/dashboard");
  // => Navigate directly to dashboard
  // => Authentication handled by fixture
  // => Test focuses on business logic

  await expect(authenticatedPage.locator("h1")).toHaveText("Dashboard");
  // => Assert dashboard loaded
  // => Clear test intent
  // => No login noise
});

test("user updates profile", async ({ authenticatedPage }) => {
  // => Second test with auth fixture
  // => Automatically authenticated
  // => Reuses fixture setup

  await authenticatedPage.goto("https://example.com/profile");
  // => Direct navigation (already logged in)

  await authenticatedPage.fill("#email", "newemail@example.com");
  // => Update profile field
  // => Test focuses on profile logic
  // => Authentication abstracted away

  await authenticatedPage.click('button:has-text("Save")');
  await expect(authenticatedPage.locator(".success-toast")).toBeVisible();
  // => Assert update successful
});

// Good: LoginPage handles only login
class LoginPage {
  async login() {}
  async forgotPassword() {}
}

// Good: DashboardPage handles only dashboard
class DashboardPage {
  async logout() {}
  async navigateToProfile() {}
}

// Bad: MixedPage handles multiple pages
class MixedPage {
  async login() {}
  async updateProfile() {} // Wrong page
}

// Good: Business-level method
class CartPage {
  async addItemToCart(itemName: string, quantity: number) {
    await this.searchItem(itemName);
    await this.selectQuantity(quantity);
    await this.clickAddToCart();
  }
}

// Bad: Exposing low-level locators
class CartPage {
  get addButton() {
    return this.page.locator("#add-btn");
  }
  // Tests shouldn't access locators directly
}

// Good: Fixture provides setup
export const test = base.extend({
  cartWithItems: async ({ page }, use) => {
    // Setup: Add items to cart
    await use(page);
    // Teardown: Clear cart
  },
});

// Bad: beforeEach in every test file
test.beforeEach(async ({ page }) => {
  // Repeated setup across files
});

// Good: Composition
class CheckoutPage {
  cart: CartPage;
  payment: PaymentPage;

  constructor(page: Page) {
    this.cart = new CartPage(page);
    this.payment = new PaymentPage(page);
  }
}

// Bad: Deep inheritance
class CheckoutPage extends CartPage {}