How to Run Unit, Browser, and JavaScript Tests in Brave Browser

Run C++ unit tests with npm run test brave_unit_tests, browser integration tests with npm run test brave_browser_tests, and JavaScript tests with cd src/brave && npm run test-unit after setting up the Brave development environment.

The brave/brave-browser repository serves as the build orchestration layer for the Brave web browser, pulling Chromium sources and applying Brave-specific patches and features. To maintain stability across the C++ core and JavaScript UI layers, contributors must run unit, browser, and JavaScript tests in Brave locally before submitting pull requests, as enforced by the repository's CONTRIBUTING.md and pull request templates.

Understanding Brave's Test Architecture

Brave organizes testing into three distinct suites that cover different layers of the browser stack. The C++ unit tests (brave_unit_tests) validate low-level utility classes, IPC mechanisms, and networking logic. The browser integration tests (brave_browser_tests) launch headless Brave instances to exercise full UI flows and component interactions. The JavaScript unit tests target the React-based UI components and Brave UI library located in the src/brave directory (the brave-core submodule).

Prerequisites for Running Tests

Before executing any test commands, you must initialize the Brave development environment and generate the build configuration files.

1. Clone the repository and initialize submodules:

   git clone https://github.com/brave/brave-browser.git
   cd brave-browser

2. Install build dependencies including depot_tools, Node.js, npm, and Python 3. Run the appropriate install script for your platform:

   ./tools/install-build-deps.sh  # Debian/Ubuntu example
   

3. Generate GN build files to create the ninja build configuration and npm test wrappers:

   ./tools/gn gen out/Default

4. Build test targets (optional). The npm run test commands will trigger builds automatically if needed, but you can pre-build:

   ninja -C out/Default brave_unit_tests brave_browser_tests

Running C++ Unit Tests (brave_unit_tests)

The brave_unit_tests target covers low-level C++ logic using GoogleTest. These tests run quickly and do not require a full browser instance.

Execute the full suite:

npm run test brave_unit_tests

This command invokes the GN test runner for the brave_unit_tests target defined in the BUILD.gn files under src/. Output follows standard GoogleTest formatting with file and line numbers for failures.

Filter specific test cases using the --gtest_filter flag:

npm run test brave_unit_tests -- --gtest_filter=BraveComponentUpdaterTest.*

Running Browser Integration Tests (brave_browser_tests)

The brave_browser_tests target launches headless Brave instances to validate UI flows, component integration, and end-to-end scenarios. These tests take longer to execute than unit tests.

Run the full browser test suite:

npm run test brave_browser_tests

The test harness starts a headless Brave process, executes the specified test cases, and shuts down the instance. As implemented in brave/brave-browser, this uses Chromium's browser test framework.

Filter specific suites or run in non-headless debug mode:

# Run only tests matching a specific filter

npm run test brave_browser_tests -- --gtest_filter=TabStripModelTest.*

# Run with visible browser window for debugging

npm run test brave_browser_tests -- --debug

Running JavaScript Unit Tests

JavaScript tests validate React components, the Brave UI library, and other frontend logic. These reside in the src/brave directory, which contains the brave-core submodule.

Navigate to the Brave source directory and execute the Jest-based test runner:

cd src/brave
npm run test-unit

The test-unit script invokes Jest against the UI code. You can pass standard Jest flags for watch mode or coverage reports:

# Run in watch mode for development

npm run test-unit -- --watch

# Generate coverage report

npm run test-unit -- --coverage

Common Test Commands and Options

Flag	Target	Description
--gtest_filter=Pattern	C++ and Browser	Run only tests matching the GoogleTest pattern (e.g., SuiteName.TestName).
--debug	Browser	Launch the browser in non-headless mode for visual debugging.
--watch	JavaScript	Re-run JavaScript tests when source files change.
--coverage	JavaScript	Generate Istanbul/Jest coverage reports for UI code.

Summary

• C++ unit tests (brave_unit_tests) validate low-level logic via npm run test brave_unit_tests using GoogleTest.
• Browser tests (brave_browser_tests) exercise UI flows in headless instances via npm run test brave_browser_tests, with optional --debug for visual inspection.
• JavaScript tests run from src/brave using npm run test-unit to validate React components and UI libraries with Jest.
• All test targets are defined in BUILD.gn files and invoked through npm wrappers that interface with Chromium's GN build system.

Frequently Asked Questions

How do I run a single specific test or test suite in Brave?

For C++ and browser tests, append the --gtest_filter flag to the npm command. For example, npm run test brave_unit_tests -- --gtest_filter=BraveAdBlockTest* runs only tests starting with that prefix. For JavaScript tests, use Jest's pattern matching: npm run test-unit -- --testNamePattern="ComponentName".

Where are the JavaScript test files located in the Brave repository?

JavaScript unit tests reside within the src/brave directory, which contains the brave-core submodule. This directory houses React components, the Brave UI library, and their corresponding test files. You must navigate to this directory to execute npm run test-unit as the npm scripts are defined in the package.json located there.

Can I run Brave browser tests in a visible window instead of headless mode?

Yes. Append the --debug flag when running browser tests to launch a non-headless Brave instance. Use the command npm run test brave_browser_tests -- --debug. This allows you to observe UI interactions visually and is useful for debugging failing tests that involve rendering or user gestures.

What should I do if npm test commands fail with missing target errors?

Ensure you have generated the GN build files with ./tools/gn gen out/Default and that the out/Default directory exists. The npm test wrappers rely on the GN build configuration to locate the brave_unit_tests and brave_browser_tests targets defined in the BUILD.gn files. If dependencies are missing, run ./tools/install-build-deps.sh to install required system packages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}