Netzenbot
5bb907f22d
Add upstream test failures best practices doc Consolidates upstream-flake filter guidance from testing-isolation.md (TI-031, TI-032, TI-041, TI-042, TI-043) and patches.md (PATCH-011) into a dedicated testing-upstream-failures.md. Expands the flake-check section with full script usage and the LUCI verdict table.
5.0 KiB
5.0 KiB
Brave Browser Best Practices
This document is an index of best practices for the Brave Browser codebase, discovered from code reviews, test fixes, and development experience. Each section links to a detailed document.
Nala / Leo Design System
- Nala / Leo Design System - Icons (Android, WebUI, C++), Android color tokens, Leo component usage
Code & Architecture
- Architecture and Code Organization - Layering violations, dependency injection, factory patterns, pref management
- C++ Coding Standards - IWYU, naming conventions, CHECK vs DCHECK, style, comments, logging
- C++ Memory, Lifetime & Threading - Ownership, WeakPtr, Unretained, raw_ptr, KeyedService shutdown, threading
- C++ API Usage, Containers & Types - base utilities, containers, type safety, optional, span, callbacks
- Documentation - Inline comments, method docs, READMEs, keeping docs fresh, avoiding duplication
- Localization & String Resources - GRD/GRDP conventions, string descriptions, placeholders, UI text voice, i18n patterns
- Brave Style Guide - Voice, capitalization, punctuation, product naming, accessibility, privacy/security terms, product messaging
- Front-End (TypeScript/React) - Component props, spread args, XSS prevention
- Android (Java/Kotlin) - Activity/Fragment lifecycle, null safety, LazyHolder singletons, theme handling, Robolectric, bytecode patching, NullAway (
@Nullableplacement,@MonotonicNonNull, assert/assume patterns, destruction, view binders, Supplier variance, JNI nullness) - chromium_src Overrides - Overrides vs patches, minimizing duplication, ChromiumImpl fallback
- Build System - BUILD.gn organization, buildflags, DEPS, GRD resources
- UI/Views - Desktop C++ views, view hierarchy, layout, styling
- Patches - Patch style, minimality, extensibility via defines/includes, GN patch patterns
- Plaster - Plaster patch configuration patterns and best practices
- iOS (Swift/ObjC/UIKit) - Swift idioms, SwiftUI, UIKit lifecycle, ObjC bridge, Tab architecture, chromium_src iOS overrides
Testing
- Async Testing Patterns - Root cause analysis, RunUntil, RunUntilIdle, nested run loops, TestFuture
- JavaScript Evaluation in Tests - MutationObserver, polling loops, isolated worlds, renderer setup
- Navigation and Timing - Same-document navigation, timeouts, page distillation
- Test Isolation and Specific Patterns - Fakes, API testing, HTTP request testing, throttle testing, Chromium patterns
- Upstream Test Failures - When to use filter files vs fix tests, checking upstream flakiness via LUCI Analysis, filter file conventions
Quick Checklist
Before writing async tests, verify:
- No
RunLoop::RunUntilIdle()usage - No
EvalJs()orExecJs()insideRunUntil()lambdas - Using manual polling loops for JavaScript conditions
- Using
base::test::RunUntil()only for C++ conditions - Waiting for specific completion signals, not arbitrary timeouts
- Using isolated worlds (
ISOLATED_WORLD_ID_BRAVE_INTERNAL) for test JS - Per-resource expected values for HTTP request testing
- Large throttle windows for throttle behavior tests
- Proper observers for same-document navigation
- Testing public APIs, not implementation details
- Searched Chromium codebase for similar patterns
- Included Chromium code references in comments when following patterns
- Prefer event-driven JS (MutationObserver) over C++ polling for DOM changes
References
- Chromium Browser Design Principles - Feature scoping, modularity, UI patterns, lifetime management
- Chromium C++ Testing Best Practices
- Chromium C++ Style Guide
- Chromium Smart Pointer Guidelines
- Chromium Container Guidelines
- Chromium Componentization Cookbook