chrome-devtools-mcp/AGENTS.md

This repository contains an MCP server and CLI for Chrome DevTools.

Instructions

• Use only scripts from package.json to run commands.
• Use npm run build to run tsc and test build.
• Use npm run test to build and run tests, run all tests to verify correctness.
• Use npm run test path-to-test.ts to build and run a single test file, for example, npm run test tests/McpContext.test.ts.
• Use npm run format to fix formatting and get linting errors.
• Never modify third_party/devtools-frontend except for experimentation: it is a git submodule, a mirror of the actual codebase.

Rules for TypeScript

• Do not use any type.
• Do not use as keyword for type casting.
• Do not use ! operator for type assertion.
• Do not use // @ts-ignore comments.
• Do not use // @ts-nocheck comments.
• Do not use // @ts-expect-error comments.
• Prefer for..of instead of forEach.
• Never type-check types that are already type safe (e.g. redundant typeof checks on statically typed variables).

Rules for Testing

Structure and Separation of Concerns

• Prefer mock-based unit tests over real-browser tests: Do not use withMcpContext or launch a real browser unless the test genuinely requires real browser or DevTools protocol integration (e.g., live CDP events, browser lifecycle, secondary sessions). Puppeteer already tests browser behavior upstream; unit tests run faster and avoid browser overhead.
• Tool handler tests (tests/tools/*.test.ts):
  • Test that the tool handler parses/validates parameters and invokes the corresponding methods on page, context, or response with the exact expected arguments.
  • Do not reimplement business logic or state tracking inside mocks (e.g., do not simulate state changes in mock methods).
• Core class tests (e.g., tests/McpPage.test.ts):
  • Test business logic by instantiating the real class under test with mocked dependencies (e.g., instantiate new McpPage(...) with a mocked Puppeteer page from createMockPuppeteerPage()).
  • Assert that the class calls the underlying Puppeteer methods with the expected parameters.

Mocking Guidelines (tests/mocks.ts)

• Centralize mocks in tests/mocks.ts: Keep all reusable mock factories in tests/mocks.ts. Import directly from tests/mocks.ts (do not re-export from tests/utils.ts).
• Use sinon.createStubInstance(Class): Do not hand-roll mock objects or define custom mock interfaces. Use sinon.createStubInstance() so all prototype methods are automatically stubbed.
• Typing: Use sinon.SinonStubbedInstance<Class> for mock types (e.g., MockMcpPage, MockMcpContext, MockMcpResponse).
• Handler mocks helper: For tool handlers, use const {page, context, response} = createHandlerMocks(); from tests/mocks.ts to set up all three mocks in one call.
• Keep mocks generic: Do not tailor mocks to a specific tool or test suite.
• Naming conventions: Use mock rather than fake in helper and variable names (e.g., createMockPuppeteerPage, createMockMcpPage). Name the mocked Puppeteer page instance pptrPage.

Assertions and Sinon Best Practices

• Use sinon.assert methods: Do not use Node's assert.ok(stub.calledOnce) or assert.deepStrictEqual(stub.firstCall.args[0], ...) to verify stub calls.
• Verify exact arguments:
  • Use sinon.assert.calledOnceWithExactly(stub, ...args) for single calls with exact arguments.
  • Use sinon.assert.calledWithExactly(stub.secondCall, ...args) for subsequent calls.
  • Use sinon.assert.notCalled(stub) to assert a method was not invoked.
• Clean up stubs: tests/setup.ts runs sinon.restore() after every test. Do not add afterEach(() => sinon.restore()); to test suites.

Test Cleanliness

• Do not add redundant comments or verbose JSDoc for short, self-describing mock functions or tests.
• Only test real scenarios; avoid testing redundant or artificial calls that cannot happen in real usage.
• Use current year (2026) in copyright headers for new test files.

Pre-submit checklist

Complete every item before you upload a PR or push a new revision.

Scope and PR description

• The PR contains one change. Move unrelated refactors, renames, formatting changes, and build or compiler changes into their own PR.
• The PR title, the commit type (fix:, feat:, chore:), and the squash commit message describe the same change. A change to a default value or to tool output is a fix: or a feat:, not a chore:.
• The PR description lists every user-visible behavior change, including changes to other tools that share the changed code path.
• The PR description matches the shipped behavior. Remove claims about fixes that the diff does not contain.
• The PR description names new functions that have no production caller yet, or the PR removes them.
• The branch has no merge conflicts with main. Rebase only when a conflict exists.
• npm run gen ran after a change to a tool schema, a tool description, or a CLI option. The generated files are committed.
• npm run format ran. No line is longer than 80 columns.
• npm run test passed locally. CI failures on all platforms are your responsibility.

Design

• The change lives in the lowest layer that owns the data: page logic in McpPage, context logic in McpContext, formatting in src/formatters/*. McpResponse does not resolve pages or workers.
• If Puppeteer or devtools-frontend owns the bug, fix it there first. Do not copy or re-implement upstream code in this repository.
• Puppeteer internals are imported only through src/third_party/index.ts.
• Repeated code is one helper. Extract a helper when the same block appears two or more times. Prefer an existing helper or a Puppeteer utility (for example Deferred) over a new one.
• A new formatter class exposes toJSON() and toString(), and toString() uses the toJSON() output.
• A function with three or more optional parameters takes one options object. Do not pass positional undefined placeholders.
• Each default value is declared in one place.
• A new behavior is opt-in by default when a wrong classification fails silently (for example a config option is restart-required unless the author marks it reloadable).
• An invalid combination of flags or options is rejected by the type system where possible, not only by a comment.
• No public method exists only to serve a test. Put shared helpers in src/utils/*.
• Parameter validation lives in the Zod schema (refine, coerce), not in the handler. Validation runs before the handler changes any state.
• Numeric validation matches what the consumer accepts. Use Number.isInteger and a range check where CDP expects integers.

Correctness and edge cases

• A failed external call does not leave stale state. Restore the previous value when a call rejects.
• An error path still produces the artifacts and partial results the agent needs before it throws.
• An async operation that a timeout can abandon checks that its target (browser, page, config) is still current when it resumes.
• A lock or guard is acquired and released exactly once. A helper that releases a guard throws when the guard is already released.
• Concurrent callbacks (watchers, reloads, event handlers) are serialized. A transient failure does not trigger a callback.
• A filesystem operation that races with another process tolerates the race (fs.rmSync(path, {force: true}) or try/catch), not existsSync + an unguarded call.
• A failed lookup falls back to the previous behavior. It does not turn a healthy state into an error state.
• No synchronous process spawn or blocking call runs in a polling loop or in a hot function.
• dispose() releases every resource the object created, and runs for objects that are already closed.
• Event listeners added for one action are removed when the action ends.
• Cached page-side state is refreshed before use. The page can reload between tool calls.
• Behavior shared by all tools that act on the selected page also runs for tools defined with defineTool, not only definePageTool.
• String and URL parsing handles userinfo, escaped delimiters, ports, pattern groups, and empty or whitespace-only input. Use the full authority, not a heuristic on the first or last character.
• Truncation uses Intl.Segmenter graphemes, not string.slice.
• Secrets never reach logs. Redact headers, URL userinfo, and query strings in every log line, including process startup arguments.
• A filesystem path parameter is validated with validatePath() even when the value parses as a URL. The error says what the parameter expects.
• A value that crosses a process boundary (daemon IPC, CLI) is serialized with JSON.stringify when it is not a primitive.
• An identifier is issued only for items that a tool can resolve later.
• A dedup key never collapses for items without identifying fields. Use a counter or skip such items.
• An error message names the exact condition that failed, with the relevant values (pid, timeout, URL, parameter name).
• A thrown non-Error value keeps its content in the error message. Treat objects with a string message like Error.
• Optional chaining and ?? default are not applied to values whose type is non-optional.
• Version-dependent behavior (Node, Chrome, OS) is tested on every version the engines field allows, or the test does not depend on it.

Tests

• Every new or changed function has a test that calls it. A function with no caller in src/ and no test is removed from the PR.
• Every review request of the form "add a test for X" has a test whose name includes X.
• A new test for a bug fails on main without the fix. Remove assertions that pass with and without the fix.
• A notCalled assertion targets the first method the handler calls after the step under test, not a method inside a callback that a stub never runs.
• A test for a selected branch also asserts that the other branch was not taken.
• Assertions use calledOnceWithExactly or calledWithExactly(stub.nthCall, ...). Use calledOnceWithMatch only for arguments that cannot be exact (for example an AbortSignal) or when an overloaded signature forces sinon.match.same.
• Options that the handler derives from its input are asserted, not only the call count.
• Test names describe the asserted behavior. Rename the test when the assertion changes.
• if (value) { assert... } does not appear in tests. Use assert.ok(value) before the dependent assertions.
• Real-browser tests exist only for behavior that mocks cannot observe. A test file contains at most one slow end-to-end run per scenario.
• A real-browser test that counts requests filters favicon.ico.
• A real-browser test that waits for CDP events waits on the session or result of the code under test, not on a new createCDPSession().
• Every awaited event in a test has a bounded timeout. Positive-path tests poll for the condition instead of a fixed sleep.
• New reusable stubs and fixtures live in tests/mocks.ts and build on sinon.createStubInstance. No hand-rolled fixture uses as unknown as.
• Mock options that equal the default value are not passed.
• Temporary directories use using dir = createTempDir(...) from tests/utils.ts, not fs.mkdtemp.
• A test never reads the developer's home directory and never calls process.exit. Stub locators and pass exitProcess = false.
• When a real-browser test is replaced with mocks, each branch the old test covered still has a test.
• A test does not repeat a round-trip that another test already covers. Stop after the first assertion that proves the change.

Documentation and output

• A tool description states the exact behavior, including when a parameter is ignored or depends on another parameter.
• Skills stay generic. Add one short note in the tool-selection section instead of a feature-specific workflow.
• Inline comments are one sentence. Remove comments that repeat an existing TSDoc.
• Response text that depends on a condition prints only when the condition is true.