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

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.

Feb 20 '25 20:02 jonathanphilippou

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.