# CLAUDE.md

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

## Project Overview

This is a Playwright test automation project for SmartDocs 360 login functionality, part of a workshop series on using Claude Code with Playwright. The project demonstrates automated browser testing with multi-factor authentication (TOTP).

## MCP Server Configuration

This project uses Model Context Protocol (MCP) servers configured in `.claude.json`:

- **Sequential Thinking Server**: Provides structured reasoning capabilities for complex problem-solving
- **Playwright MCP Server**: Enables browser automation and interaction through Claude Code

These MCP servers extend Claude Code's capabilities for browser automation tasks.

## Running Tests

```bash
# Run all tests (headless)
npm test

# Run tests with browser visible
npm run test:headed

# Run tests with Playwright UI mode (interactive)
npm run test:ui

# Run tests in debug mode with step-through
npm run test:debug

# View test report after running tests
npm run report
```

## Test Configuration

The project is configured via `playwright.config.ts`:

- **Base URL**: `http://localhost:3000` (configured but tests use external URLs)
- **Test Directory**: `./tests`
- **Browser Projects**: Chromium, Firefox, and WebKit
- **Parallel Execution**: Enabled by default (disabled in CI with 1 worker)
- **Retries**: 2 retries in CI, 0 locally
- **Tracing**: Enabled on first retry for debugging

## SmartDocs 360 Test Environment

Tests target the SmartDocs 360 UAT environment:

- **SSO URL**: `https://sso.uat.bgl360.com.au/?app=smartdocs&&appFilter=smartdocs`
- **Authentication**: Multi-factor authentication with TOTP (Time-based One-Time Password)
- **Test Credentials**: Available in `LOGIN_FLOW.md`

## Authentication Flow

SmartDocs 360 uses a two-step authentication process documented in `LOGIN_FLOW.md`:

1. **Username/Password Authentication**: Uses test IDs (`username-input`, `password-input`, `submit-button`)
2. **MFA with TOTP**: Requires 6-digit code generated from secret key using HMAC-SHA1
3. **Post-Login Redirect**: To `https://uat.bglsmartdocs.com/host/#/entities`

### TOTP Generation

The login flow requires generating TOTP codes. Implementation is provided in `LOGIN_FLOW.md` using Node.js built-in `crypto` module. The algorithm follows RFC 6238:
- Base32 decode the secret key
- Calculate time counter (Unix timestamp / 30 seconds)
- Generate HMAC-SHA1 hash
- Extract 6-digit code

## Test Structure

Tests are located in the `./tests` directory with TypeScript support. The example test demonstrates basic Playwright usage patterns:

- Page navigation
- Element interaction expectations
- Async/await patterns

## Development Workflow

When creating tests for SmartDocs 360 login:

1. Use Playwright MCP tools to explore the login interface interactively
2. Generate TOTP codes using the provided `totpKey` for multi-factor authentication
3. Create reusable fixtures for authenticated sessions to avoid repeating login steps
4. Document test plans before implementation to ensure comprehensive coverage

## TypeScript Configuration

The project uses TypeScript with strict mode disabled. Type checking is provided by `@types/node` and `@playwright/test` definitions.
