Browser4 Multi-Module Maven Development

Expert development assistant for Browser4, a lightning-fast, coroutine-safe browser automation framework built with Kotlin and Java in a multi-module Maven architecture.

Project Structure

Browser4 is a multi-module Maven project with the following core modules:

Build Commands

Quick Build (Skip Tests)

**Linux/macOS:**

```bash

./mvnw -q -DskipTests

```

**Windows (cmd):**

```cmd

mvnw.cmd -q -DskipTests

```

Test Core Modules

**Linux/macOS:**

```bash

./mvnw -pl pulsar-core -am test -Dsurefire.failIfNoSpecifiedTests=false

```

**Windows (cmd):**

```cmd

mvnw.cmd -pl pulsar-core -am test -D"surefire.failIfNoSpecifiedTests=false"

```

**Note:** Windows requires quoting -D parameters with dots: `-D"key.with.dots=value"`

Build Scripts

Development Principles

Follow these core principles when making changes:

1. **最小改动 (Minimal changes)** - Make the smallest change necessary to achieve the goal

2. **保持风格 (Maintain existing style)** - Follow established code patterns and conventions

3. **清晰日志 (Clear logging)** - Use structured logging with placeholders, never string concatenation

4. **自动校验与测试 (Automated validation and testing)** - Every change must include appropriate tests

Key APIs and Components

Browser Automation

Agent System

Session Management

Kotlin Style Guidelines

Logging Standards

**Format:** See `docs/log-format.md`

**Style:** Always use placeholders, never string concatenation

```kotlin

// Correct

logger.info("Task {} finished in {} ms", taskId, cost)

// Avoid

logger.info("Task " + taskId + " finished in " + cost + " ms")

```

Configuration

- `docs/config.md`

- `docs/rest-api-examples.md`

Testing Requirements

Test Locations

Speed Targets

Coverage

Test Requirements for Changes

- Happy path test

- At least 1 edge case/boundary condition test

Definition of Done

Before considering any change complete, verify:

1. ✅ Build and relevant tests pass with no new high-noise logs/warnings

2. ✅ New/changed logic includes happy path + at least 1 boundary case test

3. ✅ No secrets, private endpoints, or unvalidated inputs committed

4. ✅ No arbitrary version drift (follow parent BOM)

5. ✅ Public behavior/configuration changes documented

6. ✅ Potential performance impact (>≈5%) assessed or benchmarked

Troubleshooting

Common Issues

**Linux/macOS: mvnw permission denied**

```bash

chmod +x mvnw

```

**JDK version mismatch**

**Windows parameter escaping**

**Port already in use (default 8182)**

**Log storms from CDP retries**

Testing Strategies

**Browser CDP issues**

**Proxy/Privacy concerns**

**Structured logging**

Reference Documentation

Quick Reference

When working on this project:

1. Start with minimal changes that maintain existing style

2. Use Maven wrapper commands appropriate for your OS

3. Quote -D parameters on Windows

4. Write clear, structured logs with placeholders

5. Follow Kotlin conventions (immutability, explicit types, null safety)

6. Include tests for happy path + edge cases

7. Verify Definition of Done before committing

8. Reference project docs for configuration and patterns