rust_browser/docs/development-guide.md

Development Guide — rust_browser

Generated: 2026-03-05 | Scan Level: Deep

Prerequisites

• Rust toolchain — Stable channel (pinned via rust-toolchain.toml)
  • Components: rustfmt, clippy
• just command runner

  cargo install just
  

• Python 3 — Required for WPT/Test262 scripts only

Getting Started

Clone and Build

git clone <repo-url> rust_browser
cd rust_browser
cargo build -p app_browser

Run the Browser

# Show CLI help
cargo run -p app_browser -- --help

# Open a URL in windowed mode
cargo run -p app_browser -- https://example.com

# Open with dark mode
cargo run -p app_browser -- --dark https://example.com

# Render to layout dump (no window)
cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html

# Render to PNG
cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html --png

Development Commands

All primary commands are in the justfile:

Command	Purpose	Duration
just ci	Full CI pipeline (fmt + lint + test + policy + metrics)	~1 min
just test	Run all tests (workspace + WPT + JS262 manifests)	~30s
just lint	Run clippy with warnings denied	~15s
just fmt	Check formatting (no changes)	~5s
just fix	Auto-fix formatting	~5s
just policy	Run safety checks (unsafe, deps, file sizes)	~5s
just metrics	Report project metrics	~5s
just san	Run sanitizers (Linux nightly only)	~5min

CI Workflow

Always run just ci after every code change. It takes about 1 minute.

# Capture output for review
just ci 2>&1 | tee /tmp/ci-output.txt

Testing

Test Layers

1. Unit tests — Inline #[cfg(test)] mod tests in crate source files

   cargo test -p <crate_name>
   

2. Integration tests — tests/*.rs (each registered as [[test]] in root Cargo.toml)

   cargo test -p rust_browser --test goldens
   cargo test -p rust_browser --test js_tests
   

3. Golden tests — Layout tree and display list regression tests

   cargo test -p rust_browser --test goldens
   # Regenerate expected outputs:
   cargo test -p rust_browser --test regen_goldens -- --ignored --nocapture
   

4. JS262 conformance — Test262-inspired JavaScript conformance suite

   # Run vendored tier-1 suite
   cargo test -p rust_browser --test js262_harness js262_suite_matches_manifest_expectations -- --nocapture
   
   # Promote passing known_fail tests
   just js262-status promote --id <test-id>
   

5. WPT harness — Web Platform Tests

   cargo test -p rust_browser --test wpt_harness wpt_suite_matches_manifest_expectations -- --nocapture
   

6. Full Test262 suite (requires upstream clone)

   just clone-test262    # Clone tc39/test262
   just test262-scan     # Generate manifest
   just test262-full     # Run full suite
   just triage-test262-full  # Promote newly passing tests
   

Adding New Integration Tests

1. Create tests/my_test.rs
2. Add to root Cargo.toml:

   [[test]]
   name = "my_test"
   path = "tests/my_test.rs"
   

Test Principles

• Every bug fix requires a regression test
• Unit tests go inline in the source module (test private APIs)
• Integration tests go in tests/ (test public cross-crate behavior)
• Golden tests for any rendering behavior change

Project Structure Rules

Layer Dependencies

Layer 3: app_browser    → can depend on anything below
Layer 2: browser_runtime → can depend on Layer 1 and 0
Layer 1: engine crates   → can depend on Layer 1 and 0 (no upward deps)
Layer 0: shared          → no internal dependencies

Enforced by scripts/check_deps.sh — runs in CI.

Unsafe Code Policy

• Forbidden by default — unsafe_code = "forbid" in workspace lints
• Allowed only in: crates/platform/ and crates/graphics/
• Enforced by scripts/check_unsafe.sh — runs in CI

New Dependencies

• Require rationale in PR description
• Must pass deny.toml license/advisory checks

Common Development Tasks

Adding a New CSS Property

1. Add parsing in crates/css/ (tokenizer + parser)
2. Add selector/cascade support in crates/selectors/ if needed
3. Add computed style type in crates/style/ (ComputedStyles)
4. Implement layout behavior in crates/layout/
5. Add display list generation in crates/display_list/ if visual
6. Update docs/CSS2.1_Implementation_Checklist.md
7. Add golden tests for the new property
8. Run just ci

Adding a New JavaScript Feature

1. Add tokenization in crates/js_parser/ (if new syntax)
2. Add AST node in crates/js_parser/
3. Implement execution in crates/js_vm/
4. Add unit tests inline
5. Add Test262 conformance tests to the manifest
6. Update docs/js_feature_matrix.md
7. Run just ci

Adding a New HTML Element

1. Add parsing support in crates/html/
2. Add DOM representation in crates/dom/ if needed
3. Add default styling in crates/style/ (UA stylesheet)
4. Implement layout behavior in crates/layout/
5. Update docs/HTML5_Implementation_Checklist.md
6. Add golden tests
7. Run just ci

Investigating Rendering Issues

Use the investigation workflow:

# Creates a report at investigations/<site>/report.md

Existing investigations: acid2, google, moldybits, slashdot, youtube

Code Style

• Formatting: rustfmt (checked by just fmt)
• Linting: clippy with all warnings denied
• Naming: Standard Rust conventions (snake_case functions, PascalCase types)
• Error handling: anyhow for application errors, thiserror for library errors
• Logging: tracing crate for structured logging

Project Metrics

Run just metrics to see:

• Lines of code per crate
• Test count
• Dependency count
• File sizes