Added on.('network' listener)

[anonx3247]

why

Added network-recording capabilities to Stagehand

what changed

• .on, .once, and .off methods can now have a "network" event instead of "console"
• Moved previous implementations into onConsoleEvent, onceConsoleEvent, and offConsoleEvent.
• Added NetworkMessage type as a wrapper over Response and Request CDP events.

test plan

• Added packages/core/lib/v3/tests/page-network.spec.ts to test all these options.

---

Summary by cubic

Adds a "network" event to Page.on/once/off to capture requests and responses via a new NetworkMessage. Enables network recording across main and child CDP sessions, with tests covering the API.

• New Features

  • Added NetworkMessage wrapping CDP request and response events (url, method, headers, status, statusText, mimeType, resourceType, requestId, frameId, loaderId, fromCache, fromServiceWorker).
  • Page.on/once/off now support "network"; listeners are installed across all sessions using Network.enable and handle errors safely.
  • Exported NetworkMessage and NetworkListener in public types.
  • Added tests (page-network.spec.ts) for request/response capture, once/off, headers, resource types, multi-page, and type inference.

• Refactors

  • Console event APIs moved to onConsoleEvent/onceConsoleEvent/offConsoleEvent without changing behavior.

^{Written for commit 32cff87. Summary will update automatically on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 32cff87

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[greptile-apps]

Greptile Overview

Greptile Summary

Added network event listener capabilities to Stagehand's Page class, mirroring the existing console event API.

• Implemented NetworkMessage class wrapping CDP request/response events with clean accessor methods
• Extended .on(), .once(), and .off() methods to support "network" event type
• Network listeners capture both Network.requestWillBeSent and Network.responseReceived CDP events
• Follows the same pattern as existing console event handling (lazy CDP setup, error isolation, multi-session support)
• Added comprehensive test coverage for all network event scenarios

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean implementation that closely follows existing console event pattern. Well-structured code with proper error handling, TypeScript typing, and comprehensive tests. No breaking changes to existing APIs.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/lib/v3/understudy/networkMessage.ts	5/5	New file implementing NetworkMessage class as a wrapper over CDP network events with clean API methods for accessing request/response data
packages/core/lib/v3/understudy/page.ts	4/5	Extended event handling with network listeners following existing console event pattern; uses CDP Network.requestWillBeSent and Network.responseReceived events
packages/core/lib/v3/types/public/page.ts	5/5	Added public exports for NetworkMessage class and NetworkListener type
packages/core/lib/v3/tests/page-network.spec.ts	5/5	Comprehensive test suite covering network event listeners, request/response capture, headers, resource types, and multi-page scenarios

Sequence Diagram

sequenceDiagram
    participant User
    participant Page
    participant CDPSession
    participant NetworkManager
    participant NetworkMessage
    participant Listener

    Note over User,Listener: Network Event Registration
    User->>Page: page.on("network", listener)
    Page->>Page: onNetworkEvent(listener)
    Page->>Page: Add listener to networkListeners Set
    alt First listener registered
        Page->>Page: ensureNetworkTaps()
        Page->>CDPSession: send("Network.enable")
        Page->>CDPSession: on("Network.requestWillBeSent", handler)
        Page->>CDPSession: on("Network.responseReceived", handler)
    end

    Note over User,Listener: Network Request Flow
    CDPSession-->>Page: Network.requestWillBeSent event
    Page->>Page: emitNetworkRequest(evt)
    Page->>NetworkMessage: new NetworkMessage({type: "request", ...})
    Page->>Listener: listener(networkMessage)

    Note over User,Listener: Network Response Flow
    CDPSession-->>Page: Network.responseReceived event
    Page->>Page: emitNetworkResponse(evt)
    Page->>NetworkMessage: new NetworkMessage({type: "response", ...})
    Page->>Listener: listener(networkMessage)

    Note over User,Listener: Listener Removal
    User->>Page: page.off("network", listener)
    Page->>Page: offNetworkEvent(listener)
    Page->>Page: Remove listener from networkListeners Set
    alt Last listener removed
        Page->>Page: removeAllNetworkTaps()
        Page->>CDPSession: off("Network.requestWillBeSent", handler)
        Page->>CDPSession: off("Network.responseReceived", handler)
    end

Loading

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

2 issues found across 4 files

Prompt for AI agents (all 2 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/tests/page-network.spec.ts">

<violation number="1" location="packages/core/lib/v3/tests/page-network.spec.ts:246">
P2: The assertions check `message.url`, `message.type`, and `message.requestId` as properties, but throughout this file they are called as methods (e.g., `message.url()`, `message.type()`). This test verifies method references exist rather than that calling them works. Consider calling them as methods: `expect(message.url()).toBeDefined()`.</violation>

<violation number="2" location="packages/core/lib/v3/tests/page-network.spec.ts:351">
P2: The variable `foundPostData` is declared and conditionally set to true, but there&#39;s no assertion checking its value. This test doesn&#39;t actually verify anything. Either add an assertion (possibly with a soft expectation given timing concerns) or convert this to documentation/example code outside the test suite.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}