Allow Stagehand to Attach to an Existing Playwright Page for Proper Video Recording in e2e testing

[jonathanphilippou]

Title:

Allow Stagehand to Attach to an Existing Playwright Page for Proper Video Recording

Summary:

When integrating Stagehand with Playwright tests, video recording fails to work as expected. The root cause is that Stagehand’s current initialization (via init() or the deprecated initFromPage()) creates its own browser context and page rather than attaching to the Playwright test runner’s page. Since Playwright’s video recording is configured at the context level (the one that the test runner creates), any actions performed in a separate Stagehand‑created context are not recorded.

What’s Happening:

• Playwright’s Test Runner:

  • Creates a browser context and page with video recording enabled (per settings like video: "retain-on-failure").
  • Expects to manage the lifecycle (creation/closure) of that context to trigger video finalization.

• Stagehand’s Current Behavior:

  • When calling init(), Stagehand creates its own browser context and page, independent of the Playwright-managed one.
  • This new context isn’t set up with video recording, so even if it’s closed later, Playwright never records the test actions.

• Result:

  • Tests that use Stagehand’s methods (like observe(), act(), etc.) run on a page that isn’t being recorded, causing missing or blank video artifacts.

Proposed Solution:

Modify Stagehand to allow its initialization to accept an existing Playwright page. Specifically:

• Extend the Initialization API:

  • Add an optional parameter (e.g., init({ page: existingPage }) or an attachToPage option) so that if a Playwright page is provided, Stagehand attaches to that page and its context.

• Behavior in "Attached" Mode:

  • Use the provided Playwright page instead of creating a new one.
  • Set the internal context to providedPage.context().
  • Avoid closing the page or context on teardown—leaving that responsibility to the test runner.

• Benefits:

  • Ensures that all Stagehand operations occur in the same context that Playwright manages.
  • Preserves Playwright’s video recording, tracing, and other artifact mechanisms.
  • Provides a consistent and reliable test environment for users leveraging Stagehand’s AI features.

Impact:

• For Users:

  • Tests will now properly record videos when using Stagehand’s methods, making debugging easier.
  • A cleaner integration between Stagehand and the Playwright test runner.

• For Maintenance:

  • Aligns Stagehand’s lifecycle management with Playwright’s, reducing confusion and potential side effects.
  • Allows continued use of AI-driven automation without sacrificing the rich artifact collection provided by Playwright.

Next Steps:

• Implement the API change in Stagehand’s initialization code.
• Add tests to ensure that when a page is attached, video recording works as expected.
• Document the new usage pattern for contributors and users.

[meddy]

I just wanted to +1 this issue. I was hoping to utilize stagehand to write/replace normal E2E playwright tests, but it appears the integration with the test runner context is a little awkward.

[hailee0710]

+1 to this

[sannajammeh]

+1 on this. We are exploring Stagehand and this is exactly whats turning us off currently

[cadeParade]

+1 to this

[cadeParade]

Looks like it previously had this feature, but was removed in v2 in favor of requiring a browserbase session id... Link

[valllabh]

+1 on this. may websites opens things in popups.

[harrismcc]

Just bumping this yet again, this would be insanely useful

[z0gSh1u]

+1

[4t145]

Is there anyone working on this now?

[eraserx99]

+1

[PavelGlebovAndritz]

+1

[seanmcguire12]

hey all, I believe this should be doable in stagehand v3. @tkattkat added an example in this PR to demonstrate. Going to close this one now.

[B4nan]

It would be good if you could reconsider this. Having a method to actually reuse an existing playwright page is exactly what I am looking for, but for different reasons. We'd like to support stagehand in https://github.com/apify/crawlee natively, and so far it seems like the only way would be either letting stagehand manage the browser (which would likely mean discarding a lot of crawlee features, and a very deep and lengthy integration) or keeping two browsers around (which means double the memory and CPU consumption, so not very usable for anything production related). Crawlee manages browser contexts automatically, and there is a lot of logic around it. Ideally, I would just start stagehand before processing a request, and attach it to the plawright page crawlee provides automatically.