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

> Learn to run unit, browser, and JavaScript tests in Brave Browser. Follow our guide for easy setup and execution of your Brave browser tests.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/brave/brave-browser/blob/main/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:
    ```bash
    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:
    ```bash
    ./tools/install-build-deps.sh  # Debian/Ubuntu example

    ```

3.  **Generate GN build files** to create the ninja build configuration and npm test wrappers:
    ```bash
    ./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:
    ```bash
    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:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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:

```bash
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:

```bash

# 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`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/./tools/install-build-deps.sh) to install required system packages.