Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• jest.config.js
• playwright.config.ts
• e2e/checkout-cod.spec.ts
• features/checkout/services/checkout.service.spec.ts
• package.json
• E2E_TESTING.md
• features/addresses/services/addresses.service.spec.ts
• features/payments/components/payment-success-dialog.spec.tsx
• features/addresses/hooks/use-addresses.spec.ts

The project employs a multi-layered testing strategy to ensure code quality, feature correctness, and application stability. This strategy encompasses unit, integration, and end-to-end (E2E) testing, leveraging industry-standard frameworks like Jest and Playwright. The goal is to validate business logic, component behavior, and critical user flows across different browsers.

The testing approach is defined in project documentation, which advocates for writing tests alongside implementation to achieve high coverage. The structure separates Jest tests for unit/integration from Playwright tests for E2E, which are located in a dedicated e2e/ directory and are ignored by the Jest test runner.

Sources: AGENTS.md:31-34, jest.config.js:18-23, E2E_TESTING.md

Testing Frameworks and Tools

The project relies on a specific set of libraries and frameworks to execute its testing strategy. These tools are defined as development dependencies in the package.json file.

Sources: package.json:44-68

Unit & Integration Testing: Jest

Jest is the primary framework for unit and integration testing. It is configured to work with Next.js and TypeScript, using jest-environment-jsdom to simulate a browser environment for testing React components.

Sources: jest.config.js, package.json:64-65

Configuration

The Jest configuration is managed in jest.config.js. Key settings include:

• Environment: jest-environment-jsdom is used to provide a DOM environment.
• Path Aliases: Module aliases like @/(.*) are mapped to <rootDir>/$1 to align with the application's tsconfig.json.
• Test Match: Tests are discovered by matching files with spec.[jt]s?(x) or test.[jt]s?(x) extensions.
• Ignored Paths: The configuration explicitly ignores the /e2e/ directory to prevent conflicts with Playwright tests.

Sources: jest.config.js:10-23

// jest.config.js
const customJestConfig = {
  setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
  moduleNameMapper: {
    // Handle module aliases
    "^@/(.*)$": "<rootDir>/$1",
  },
  testEnvironment: "jest-environment-jsdom",
  testMatch: [
    "**/__tests__/**/*.[jt]s?(x)",
    "**/?(*.)+(spec|test).[jt]s?(x)", // Match *.test.ts and *.spec.ts EXCEPT in e2e folder
  ],
  testPathIgnorePatterns: [
    "/node_modules/",
    "/.next/",
    "/e2e/", // Skip Playwright E2E tests - CRITICAL
    "/playwright/",
    "/lib/api-client.spec.ts", // api-client initialization issue with mocks
  ],
};

Sources: jest.config.js:8-25

Mocking Strategy

Unit and integration tests heavily rely on mocking to isolate components and services. Dependencies like API services, stores (Zustand), and utility functions are mocked using jest.mock(). This allows tests to focus on a specific unit of logic without making actual network requests or depending on a complex state management setup.

For example, in service-level tests, API client methods are replaced with mock functions (jest.fn()) to simulate successful or failed API responses.

The diagram below illustrates the mocking process for testing the CheckoutService.

Sources: features/checkout/services/checkout.service.spec.ts:10-26, features/addresses/services/addresses.service.spec.ts:7-22, features/addresses/hooks/use-addresses.spec.ts:7-13

End-to-End Testing: Playwright

Playwright is used for end-to-end (E2E) testing to simulate real user interactions and validate critical user flows from start to finish.

Sources: package.json:50, E2E_TESTING.md

Configuration

Playwright is configured in playwright.config.ts. The configuration specifies the browsers to test against, timeouts, and the base URL for the application under test.

Configuration Key	Value	Description
testDir	./e2e	Specifies the directory where E2E test files are located.
timeout	30 * 1000	Sets a 30-second timeout for each test.
use.baseURL	http://localhost:3000	The base URL for the application, used for navigation actions like page.goto('/').
retries	process.env.CI ? 2 : 0	Tests are retried twice in a CI environment but not during local development.
projects	chromium, firefox, webkit	Defines the set of browsers the tests will run against.
reporter	html	Generates an HTML report of the test results.

Sources: playwright.config.ts, E2E_TESTING.md:40-46

Types of Testing

Unit and Integration Tests

These tests are written with Jest and React Testing Library. They cover:

• Service Logic: Validating business logic within service classes. For instance, CheckoutService tests ensure that checkout validation rules are applied correctly and that the service calls the appropriate order and payment APIs.
• API Client Services: Testing API service layers (addressesApi, ordersApi) to ensure they call the correct endpoints with the right parameters. These tests mock the underlying api-client methods.
• React Hooks: Custom hooks like useAddresses are tested to verify state management, side effects (like fetching data on mount), and interactions with services.
• React Components: Component tests, such as for PaymentSuccessDialog, verify rendering based on props, user interactions (button clicks), and correct display of data.

Sources: features/checkout/services/checkout.service.spec.ts, features/addresses/services/addresses.service.spec.ts, features/addresses/hooks/use-addresses.spec.ts, features/payments/components/payment-success-dialog.spec.tsx

End-to-End (E2E) Tests

E2E tests are located in the e2e/ directory and are written using Playwright. They simulate complete user journeys. The project includes E2E tests for critical flows like checkout.

Sources: E2E_TESTING.md:23-37, e2e/checkout-cod.spec.ts

Example Flow: COD Checkout

The e2e/checkout-cod.spec.ts file defines a test suite for the Cash on Delivery (COD) checkout flow. The main test case validates the entire journey from adding a product to the cart to successfully placing an order.

The sequence diagram below visualizes the steps executed by Playwright in this test.

Sources: e2e/checkout-cod.spec.ts:13-70

The E2E tests cover:

• COD Flow:
  • Completing checkout and redirecting to the success page.
  • Verifying the cart is cleared after an order.
  • Navigating to the order detail page from the success page.
• SePay Flow:
  • Handling the payment dialog and QR code.
  • Verifying success confirmation and auto-redirect.

Sources: E2E_TESTING.md:26-37

Test Execution

The package.json file defines several scripts for running the different types of tests.

Script	Command	Description
test	jest	Runs all Jest unit and integration tests.
test:watch	jest --watch	Runs Jest tests in interactive watch mode.
test:e2e	playwright test	Runs all Playwright E2E tests.
test:e2e:ui	playwright test --ui	Opens the Playwright UI for interactive E2E testing.
test:e2e:debug	playwright test --debug	Runs E2E tests in debug mode.

Sources: package.json:6-11, E2E_TESTING.md:12-21