CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Playwright-based UI test automation framework for a business management system (supplier, customer, product, sales management). Uses page object pattern with Allure reporting.

Commands

npm install          # Install dependencies
npm run test:ci      # Run tests in CI mode
npm run report      # View Allure test reports
npm run save-auth    # Save authentication state to auth.json

Run a single test file:

npx playwright test tests/customer.spec.ts

Architecture

Fixture System

Two parallel fixture systems exist in fixtures/testFixture.ts:

1. test - Standard Playwright test with regular page
2. fullTest - Uses authenticatedPage from authFixture.ts (pre-authenticated)

Page objects are attached via testFixture.ts:

const { fullTest } = require('./fixtures');
fullTest('my test', async ({ customerPage, authenticatedPage }) => {
  // customerPage is attached to authenticatedPage
});

Tests using fullTest must also set storageState: 'auth.json':

test.use({ storageState: 'auth.json' });

Page Object Pattern

All page objects extend BasePage (pages/basePage.ts) which provides:

• navigate(path) - Navigate using BASE_URL/#{path}
• click/fill/selectOptionByText - Basic interactions
• waitForVisible/expectVisible/expectText - Assertions
• takeScreenshot(name) - Saves to screenshots/ directory
• attachScreenshot(testInfo, name) - Attaches to Allure report
• fillLicensePlate(plate) - Handles custom license plate keyboard input
• uploadImage(path) - Handles file upload dialogs
• selectRegion(province, city, district) - Handles region picker dialogs

Test Organization

• tests/*.spec.ts - Test specs
• pages/*.ts - Page object classes
• fixtures/*.ts - Test fixtures and authentication
• utils/dataGenerator.ts - Test data generation utilities
• auth.json - Saved authentication state (git-ignored)

Test Style

Tests use Allure step reporting and screenshot attachments:

await allure.step('Step description', async () => {
  await customerPage.createCustomer(info);
  await customerPage.attachScreenshot(testInfo, 'screenshot name');
});

Serial execution is used per test file to avoid interference:

test.describe.configure({ mode: 'serial' });

Environment

Configure in .env (copy from .env.example if exists):

• BASE_URL - Application URL (e.g., http://localhost:8080)

Key Files

• playwright.config.ts - Test configuration, reporters (Allure HTML)
• fixtures/authFixture.ts - Authentication via storageState
• fixtures/testFixture.ts - Page object fixtures and fullTest
• pages/basePage.ts - Base class with common UI interaction methods
• utils/dataGenerator.ts - Functions for generating test data (names, phones, IDs, etc.)