Project

Contributing

Mr. Browser is open source under the MIT license. Contributions of all kinds are welcome — bug reports, documentation improvements, new step types, and performance work.

# Local setup

setup

bash

# Prerequisites: Go 1.22+, Chromium, make

git clone https://github.com/aryainguz/mrbrowser.git
cd mrbrowser

# Download Go dependencies
make deps

# Build the binary
make build
# → bin/mr-browser

# Run unit tests (no Chromium needed)
make test-unit

# Run integration tests (requires Chromium in PATH)
make test-int

# Run all tests
make test

# Format + vet
make fmt
make vet

Tip

Unit tests run without Chromium and are fast (<5 s). Integration tests require Chromium in your PATH. On macOS, brew install chromium; on Ubuntu, apt install chromium-browser.

# Repository structure

directory layout

bash

mrbrowser/
├── cli/             # Cobra CLI commands (main entrypoint)
│   └── cmd/         # run.go, debug.go, screenshot.go, inspect.go, root.go
├── core/
│   ├── actions/     # Browser action primitives (Click, Type, Scroll…)
│   ├── browser/     # chromedp session wrapper
│   └── runtime/     # YAML task parsing (task.go) & execution (executor.go)
├── intelligence/
│   ├── dom/         # CDP Accessibility Tree extraction
│   └── intent/      # Intent resolution & scoring engine
├── memory/          # SQLite fingerprint store & self-healing logic
├── telemetry/       # Structured logging helpers
├── sdk/
│   ├── python/      # Python SDK (mrbrowser package)
│   └── typescript/  # TypeScript SDK (@mrbrowser/sdk)
├── docker/          # Dockerfile & docker-compose.yml
├── examples/        # Example YAML workflows
├── tests/
│   ├── unit/        # Fast unit tests
│   └── integration/ # Tests that require a live Chromium
└── docs/            # VitePress documentation site

# Adding a new step type

New YAML step types follow a four-file pattern:

adding a step

typescript

// core/runtime/task.go
// 1. Add your step struct
type ConditionalStep struct {
    Target    string `yaml:"target"`
    Condition string `yaml:"if"`
}

// 2. Add it to the Step union
type Step struct {
    // ... existing fields ...
    Conditional *ConditionalStep `yaml:"conditional,omitempty"`
}

// 3. Add Kind() case
case s.Conditional != nil:
    return "conditional"

// core/runtime/executor.go
// 4. Add execution case
case step.Conditional != nil:
    return e.execConditional(step.Conditional)

# Pull request checklist

›make fmt && make vet pass with no output
›make test-unit passes
›New code has corresponding unit tests in tests/unit/
›New step types have an example in examples/
›YAML schema changes are reflected in docs/sdk/yaml-workflows
›No new mandatory dependencies (stdlib only for SDKs)
›PR description explains the motivation and links to any related issue

# Code style

Go: Standard gofmt formatting. Exported functions and types must have doc comments. Error strings are lowercase, no trailing punctuation. Wrap errors with fmt.Errorf("context: %w", err).

Python SDK: PEP 8. All public methods must have Google-style docstrings. No external dependencies — stdlib only.

TypeScript SDK: ESM modules, strict TypeScript. No runtime dependencies — native fetch only (Node 18+).

Warning

The --no-sandbox flag must only be set by the Docker container, never hardcoded in tests or default config. It disables a Chromium security boundary and should never be the default for developer machines.