---
name: devtools-testing-guidance
description: Guidance on selecting the appropriate test suite (Unit, API, or E2E tests) when writing new tests in Chrome DevTools. MUST be used when writing new tests.
---

# Testing Guidance

This guide outlines when and how to select the appropriate test suite when writing new tests in Chrome DevTools.

> [!NOTE]
> This skill provides guidance on **which** test suite to choose when writing tests. To learn **how** to run tests, build targets, or execute linters, refer to the `devtools-verification` skill.

## Choosing a Test Suite

### 1. Unit Tests

**Default choice:** The vast majority of tests in DevTools should be unit tests.

Use unit tests for isolated testing of individual functions, classes, models, helpers, and UI components.

- **Utilities & Framework:**
  - Use `TestUniverse` (and foundation test helpers) for easy, isolated setup of required dependencies and models.
  - For testing UI widgets, use stubbed view functions and screenshot assertions rather than spinning up heavy DOM/browser infrastructure.
- **Location:** Co-located next to their implementation files (e.g. `TimelinePanel.ts` and `TimelinePanel.test.ts`).
- **BUILD.gn**: test file should be added to `devtools_ui_module("unittests")` or `devtools_foundation_module("foundation_unittests")` target in the corresponding `BUILD.gn` file.

---

### 2. API Tests

Use API tests for integration tests that verify business logic requiring more complex setups or extensive CDP (Chrome DevTools Protocol) traffic, without needing the full DevTools frontend UI.

- **When to use:**
  - Evaluating JavaScript expressions in the target page (e.g. via `Runtime.evaluate`).
  - Complex source map setups and symbolization.
  - Multi-context or target setups (workers, iframes, OOPIFs).
  - Tests that require extensive CDP mock setup.
  - Verifying the "foundational layer" of DevTools models against a real browser/web page.
- **Location:** Defined in `front_end/` with `.test.api.ts` extension (e.g. `Universe.test.api.ts`).
- **BUILD.gn**: test file should be added to `devtools_api_test_module("api_tests")` target in the corresponding `BUILD.gn` file.

---

### 3. End-to-End (E2E) Tests

Use E2E tests to verify real end-to-end user stories and user journeys.

- **When to use:**
  - Verifying full user journeys across DevTools panels and drawers.
  - Complex UI behaviors that require extensive user interaction setup and benefit from a complete DevTools frontend page connected to an inspected target page over CDP.
- **Location:** Defined in `test/e2e/` (e.g. `test/e2e/console/console-log.test.ts`).
- **BUILD.gn**: test file should be added to `ts_e2e_library(ts_e2e_library)` target in the corresponding `BUILD.gn` file. And `node_ts_library` in `test/e2e/BUILD.gn` for its dependencies.