or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-web-features.mdbrowser-page-control.mdcore-debugging.mddevice-testing.mddom-styling.mdindex.mdnetwork-performance.mdstorage-data.md
tile.json

tessl/npm-devtools-protocol

Complete Chrome DevTools Protocol JSON definitions and TypeScript types for building debugging tools and browser automation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/devtools-protocol@0.0.x

To install, run

npx @tessl/cli install tessl/npm-devtools-protocol@0.0.0

index.mddocs/

DevTools Protocol

The DevTools Protocol provides the complete Chrome DevTools Protocol specification as JSON definitions and TypeScript type declarations. It serves as the authoritative source for the DevTools Protocol, enabling developers to build debugging tools, browser automation scripts, and development environments that communicate with Chrome and other Chromium-based browsers.

Package Information

  • Package Name: devtools-protocol
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install devtools-protocol

Core Imports

TypeScript (ESM):

import Protocol from "devtools-protocol/types/protocol";
import { ProtocolMapping } from "devtools-protocol/types/protocol-mapping";
import { ProtocolProxyApi } from "devtools-protocol/types/protocol-proxy-api";

CommonJS:

const Protocol = require("devtools-protocol/types/protocol");
const { ProtocolMapping } = require("devtools-protocol/types/protocol-mapping");
const { ProtocolProxyApi } = require("devtools-protocol/types/protocol-proxy-api");

JSON Data Access:

const browserProtocol = require("devtools-protocol/json/browser_protocol.json");
const jsProtocol = require("devtools-protocol/json/js_protocol.json");

Basic Usage

import Protocol from "devtools-protocol/types/protocol";
import { ProtocolMapping } from "devtools-protocol/types/protocol-mapping";

// Using TypeScript types for debugging
function handleDebuggerPause(event: Protocol.Debugger.PausedEvent) {
  console.log("Execution paused at:", event.callFrames[0].location);
  console.log("Pause reason:", event.reason);
}

// Using protocol mappings for event handling
type DebuggerEvents = ProtocolMapping.Events;
function setupEventListener(eventName: keyof DebuggerEvents) {
  // Event handler implementation
}

// Working with JSON protocol definitions
const protocolData = require("devtools-protocol/json/browser_protocol.json");
console.log("Protocol version:", protocolData.version);
console.log("Available domains:", protocolData.domains.map(d => d.domain));

Architecture

The DevTools Protocol package is organized around several key components:

  • Protocol Namespace: Main TypeScript definitions with 53 domain-specific namespaces covering all DevTools functionality
  • JSON Definitions: Machine-readable protocol specifications in JSON format for both browser and JavaScript runtime contexts
  • Protocol Mappings: Event and command name-to-type mappings for simplified type-safe usage
  • Proxy APIs: Generated API interfaces that provide domain-specific method signatures
  • PDL Files: Protocol Definition Language files for tooling and code generation

Capabilities

Core JavaScript Debugging

Essential debugging capabilities for JavaScript execution, memory analysis, and performance profiling.

namespace Protocol.Debugger {
  interface PausedEvent {
    callFrames: CallFrame[];
    reason: ('ambiguous' | 'assert' | 'breakpoint' | 'debugCommand' | 'DOM' | 'EventListener' | 'exception' | 'instrumentation' | 'OOM' | 'other' | 'promiseRejection' | 'step');
    data?: Record<string, any>;
    hitBreakpoints?: string[];
    asyncStackTrace?: Runtime.StackTrace;
    asyncStackTraceId?: Runtime.StackTraceId;
    asyncCallStackTraceId?: Runtime.StackTraceId;
  }
}

namespace Protocol.Runtime {
  interface EvaluateRequest {
    expression: string;
    objectGroup?: string;
    includeCommandLineAPI?: boolean;
    silent?: boolean;
    contextId?: ExecutionContextId;
    returnByValue?: boolean;
    generatePreview?: boolean;
    userGesture?: boolean;
    awaitPromise?: boolean;
    throwOnSideEffect?: boolean;
    timeout?: Runtime.TimeDelta;
    disableBreaks?: boolean;
    replMode?: boolean;
    allowUnsafeEvalBlockedByCSP?: boolean;
    uniqueContextId?: string;
  }
}

Core JavaScript Debugging

Browser and Page Control

Browser-level operations, page navigation, lifecycle management, and target control.

namespace Protocol.Browser {
  interface GetVersionResponse {
    protocolVersion: string;
    product: string;
    revision: string;
    userAgent: string;
    jsVersion: string;
  }
}

namespace Protocol.Page {
  interface NavigateRequest {
    url: string;
    referrer?: string;
    transitionType?: TransitionType;
    frameId?: FrameId;
    referrerPolicy?: ReferrerPolicy;
  }
}

namespace Protocol.Target {
  interface CreateTargetRequest {
    url: string;
    width?: integer;
    height?: integer;
    browserContextId?: BrowserContextId;
    enableBeginFrameControl?: boolean;
    newWindow?: boolean;
    background?: boolean;
    forTab?: boolean;
  }
}

Browser and Page Control

DOM and Styling

DOM tree manipulation, CSS inspection and modification, and styling analysis.

namespace Protocol.DOM {
  interface GetDocumentResponse {
    root: Node;
  }
  
  interface Node {
    nodeId: NodeId;
    parentId?: NodeId;
    backendNodeId: BackendNodeId;
    nodeType: integer;
    nodeName: string;
    localName: string;
    nodeValue: string;
    childNodeCount?: integer;
    children?: Node[];
    attributes?: string[];
    documentURL?: string;
    baseURL?: string;
    publicId?: string;
    systemId?: string;
    xmlVersion?: string;
    name?: string;
    value?: string;
    pseudoType?: PseudoType;
    pseudoIdentifier?: string;
    shadowRootType?: ShadowRootType;
    frameId?: Page.FrameId;
    contentDocument?: Node;
    shadowRoots?: Node[];
    templateContent?: Node;
    pseudoElements?: Node[];
    importedDocument?: Node;
    distributedNodes?: BackendNode[];
    isSVG?: boolean;
    compatibilityMode?: CompatibilityMode;
    assignedSlot?: BackendNode;
  }
}

namespace Protocol.CSS {
  interface GetStyleSheetTextRequest {
    styleSheetId: StyleSheetId;
  }
}

DOM and Styling

Network and Performance

Network request/response analysis, performance monitoring, and resource optimization.

namespace Protocol.Network {
  interface RequestWillBeSentEvent {
    requestId: RequestId;
    loaderId: LoaderId;
    documentURL: string;
    request: Request;
    timestamp: MonotonicTime;
    wallTime: TimeSinceEpoch;
    initiator: Initiator;
    redirectHasExtraInfo?: boolean;
    type?: ResourceType;
    frameId?: Page.FrameId;
    hasUserGesture?: boolean;
  }
}

namespace Protocol.Performance {
  interface GetMetricsResponse {
    metrics: Metric[];
  }
}

Network and Performance

Device and Testing Support

Device emulation, input simulation, and testing utilities for cross-platform development.

namespace Protocol.Emulation {
  interface SetDeviceMetricsOverrideRequest {
    width: integer;
    height: integer;
    deviceScaleFactor: number;
    mobile: boolean;
    scale?: number;
    screenWidth?: integer;
    screenHeight?: integer;
    positionX?: integer;
    positionY?: integer;
    dontSetVisibleSize?: boolean;
    screenOrientation?: ScreenOrientation;
    viewport?: Viewport;
    displayFeature?: DisplayFeature;
    devicePosture?: DevicePosture;
  }
}

namespace Protocol.Input {
  interface DispatchMouseEventRequest {
    type: ('mousePressed' | 'mouseReleased' | 'mouseMoved' | 'mouseWheel');
    x: number;
    y: number;
    modifiers?: integer;
    timestamp?: TimeSinceEpoch;
    button?: MouseButton;
    buttons?: integer;
    clickCount?: integer;
    force?: number;
    tangentialPressure?: number;
    tiltX?: integer;
    tiltY?: integer;
    twist?: integer;
    deltaX?: number;
    deltaY?: number;
    pointerType?: ('mouse' | 'pen');
  }
}

Device and Testing Support

Storage and Data Management

Browser storage inspection, database analysis, and data persistence debugging.

namespace Protocol.Storage {
  interface GetStorageKeyForFrameRequest {
    frameId: Page.FrameId;
  }
}

namespace Protocol.IndexedDB {
  interface GetDatabaseNamesRequest {
    securityOrigin?: string;
    storageKey?: string;
  }
}

namespace Protocol.DOMStorage {
  interface GetDOMStorageItemsRequest {
    storageId: StorageId;
  }
}

Storage and Data Management

Advanced Web Platform Features

Modern web platform APIs including WebAuthn, Service Workers, and Progressive Web App features.

namespace Protocol.WebAuthn {
  interface AddVirtualAuthenticatorRequest {
    options: VirtualAuthenticatorOptions;
  }
}

namespace Protocol.ServiceWorker {
  interface GetVersionsResponse {
    versions: ServiceWorkerVersion[];
  }
}

namespace Protocol.PWA {
  interface GetOsAppStateRequest {
    manifestId: string;
  }
}

Advanced Web Platform Features

Data Access Patterns

JSON Protocol Access

// Load complete protocol definitions
const browserProtocol = require("devtools-protocol/json/browser_protocol.json");
const jsProtocol = require("devtools-protocol/json/js_protocol.json");

// Access protocol version information
console.log("Browser protocol version:", browserProtocol.version.major + "." + browserProtocol.version.minor);
console.log("JS protocol version:", jsProtocol.version.major + "." + jsProtocol.version.minor);

// Iterate through domains
browserProtocol.domains.forEach(domain => {
  console.log(`Domain: ${domain.domain}`);
  if (domain.commands) {
    domain.commands.forEach(cmd => console.log(`  Command: ${cmd.name}`));
  }
  if (domain.events) {
    domain.events.forEach(evt => console.log(`  Event: ${evt.name}`));
  }
});

PDL File Access

const fs = require('fs');
const path = require('path');

// Load PDL files for code generation and tooling
const browserPDL = fs.readFileSync(
  path.join(__dirname, 'node_modules/devtools-protocol/pdl/browser_protocol.pdl'), 
  'utf8'
);
const jsPDL = fs.readFileSync(
  path.join(__dirname, 'node_modules/devtools-protocol/pdl/js_protocol.pdl'), 
  'utf8'
);

// PDL files contain the source definitions used to generate JSON and TypeScript files
console.log("Browser PDL domains:", browserPDL.match(/domain \w+/g));

TypeScript Integration

import Protocol from "devtools-protocol/types/protocol";

// Type-safe event handling
function handleRuntimeConsoleAPICall(event: Protocol.Runtime.ConsoleAPICalledEvent) {
  const { type, args, executionContextId } = event;
  console.log(`Console ${type} called:`, args.map(arg => arg.value));
}

// Command parameter validation
function sendDebuggerCommand(params: Protocol.Debugger.SetBreakpointByUrlRequest) {
  // TypeScript ensures all required parameters are provided
  const { lineNumber, url, urlRegex } = params;
}

Types

// Core Protocol namespace
namespace Protocol {
  type integer = number;
}

// Key enum types from the protocol
namespace Protocol.Debugger {
  export const enum ScopeType {
    Global = 'global',
    Local = 'local',
    With = 'with',
    Closure = 'closure',
    Catch = 'catch',
    Block = 'block',
    Script = 'script',
    Eval = 'eval',
    Module = 'module',
    WasmExpressionStack = 'wasm-expression-stack',
  }

  export const enum BreakLocationType {
    DebuggerStatement = 'debuggerStatement',
    Call = 'call',
    Return = 'return',
  }

  export const enum SetPauseOnExceptionsRequestState {
    None = 'none',
    Uncaught = 'uncaught',
    All = 'all',
  }
}

namespace Protocol.Console {
  export const enum ConsoleMessageLevel {
    Log = 'log',
    Warning = 'warning',
    Error = 'error',
    Debug = 'debug',
    Info = 'info',
  }
}

// Event mapping interface
interface ProtocolMapping {
  Events: {
    [eventName: string]: any[];
  };
  Commands: {
    [commandName: string]: {
      paramsType: any[];
      returnType: any;
    };
  };
}

// Proxy API interface with domain-specific method signatures
interface ProtocolProxyApi {
  ProtocolApi: {
    Console: {
      clearMessages(): Promise<void>;
      disable(): Promise<void>;
      enable(): Promise<void>;
    };
    Debugger: {
      continueToLocation(params: Protocol.Debugger.ContinueToLocationRequest): Promise<void>;
      disable(): Promise<void>;
      enable(params?: Protocol.Debugger.EnableRequest): Promise<Protocol.Debugger.EnableResponse>;
      evaluateOnCallFrame(params: Protocol.Debugger.EvaluateOnCallFrameRequest): Promise<Protocol.Debugger.EvaluateOnCallFrameResponse>;
      pause(): Promise<void>;
      resume(params?: Protocol.Debugger.ResumeRequest): Promise<void>;
      setBreakpointByUrl(params: Protocol.Debugger.SetBreakpointByUrlRequest): Promise<Protocol.Debugger.SetBreakpointByUrlResponse>;
    };
    Runtime: {
      evaluate(params: Protocol.Runtime.EvaluateRequest): Promise<Protocol.Runtime.EvaluateResponse>;
      enable(): Promise<void>;
      disable(): Promise<void>;
      getProperties(params: Protocol.Runtime.GetPropertiesRequest): Promise<Protocol.Runtime.GetPropertiesResponse>;
    };
    // ... Additional 50+ domain APIs with specific method signatures
  };
}