CLAUDE.md

gistfile1.txt

# CLAUDE.md

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

## Mozilla Firefox WebDriver BiDi Development

This repository contains the Mozilla Firefox browser source code, with a focus on WebDriver BiDi development in the `/remote` folder.

### Key Development Commands

**Build Firefox:**
```bash
./mach build
```

**Run Firefox:**
```bash
./mach run
```

**Run WebDriver BiDi Tests:**
```bash
# Run all remote protocol tests
./mach test remote/

# Run specific WebDriver BiDi network tests (focused area)
./mach test testing/web-platform/tests/webdriver/tests/bidi/network/

# Run single test folder (faster for development)
./mach test testing/web-platform/tests/webdriver/tests/bidi/network/add_intercept/
```

**Code Quality:**
```bash
# Lint Python code
./mach lint --linter ruff

# Format/lint JavaScript
./mach lint --linter eslint
```

### WebDriver BiDi Architecture

**Core Components:**
- `/remote/webdriver-bidi/` - Main WebDriver BiDi implementation
- `/remote/shared/` - Shared utilities and message handlers
- `/remote/marionette/` - WebDriver Classic implementation
- `/testing/web-platform/tests/webdriver/tests/bidi/` - WPT test suite

**WebDriver BiDi Module Structure:**
- `modules/root/` - Root-level BiDi modules (network, browsingContext, etc.)
- `modules/windowglobal/` - Window-specific BiDi modules
- `modules/windowglobal-in-root/` - Bridge modules

**Network Module Location:**
- Implementation: `/remote/webdriver-bidi/modules/root/network.sys.mjs`
- Tests: `/testing/web-platform/tests/webdriver/tests/bidi/network/`
- Local tests: `/remote/webdriver-bidi/test/browser/`

### Testing Strategy

**Test Types:**
- **WPT Tests** - Web Platform Tests for WebDriver BiDi compliance
- **Browser Tests** - Firefox-specific integration tests (.toml files)
- **XPCShell Tests** - Unit tests for individual components
- **Puppeteer Tests** - Validation against Puppeteer test suite

**Test Execution Tips:**
- The full test suite is very large - focus on specific folders
- Network tests are in `/testing/web-platform/tests/webdriver/tests/bidi/network/`
- Use specific test paths to speed up development cycles
- Test expectations for Puppeteer are in `test/puppeteer/test/TestExpectations.json`

### File Conventions

**JavaScript Modules:**
- Use `.sys.mjs` extension for system modules
- Follow existing patterns in `/remote/webdriver-bidi/modules/`
- Implement proper error handling with WebDriver BiDi error types

**Test Files:**
- WPT tests are Python files
- Browser tests are JavaScript with `.toml` manifests
- Follow existing test structure and naming conventions

### Development Workflow

1. Make changes to WebDriver BiDi modules in `/remote/webdriver-bidi/`
2. Run focused network tests: `./mach test testing/web-platform/tests/webdriver/tests/bidi/network/add_intercept/`
3. Run local browser tests: `./mach test remote/webdriver-bidi/test/browser/`
4. Lint code before committing
5. For large changes, run broader test suites

### Documentation

- Full documentation: https://firefox-source-docs.mozilla.org/remote/
- WebDriver BiDi specification: https://w3c.github.io/webdriver-bidi/
- Setup instructions: https://firefox-source-docs.mozilla.org/setup/macos_build.html