Version 1.0: Real-World Validation - Implementation Plan

June 7, 2026 · View on GitHub

Status: 🚧 IN PROGRESS

Goal: Validate playwright-rust through real-world usage (Dogfooding Project TBD), address architectural issues discovered, and prepare for v1.0.0 release with single-crate architecture.

User Story: As a Rust developer using playwright-rust in production, I want a simple, production-ready library that works correctly as a crates.io dependency, matches official Playwright patterns, and provides comprehensive examples based on real usage.

Approach: Feedback-driven development based on v0.6+ usage and real-world integration

Key Discovery: Initial integration attempts revealed Issue #3 (build script workspace detection) which exposed fundamental complexity in the two-crate architecture. This drove the decision to consolidate to single-crate architecture (completed in v0.7.0).

Strategic Context

Version 1.0 represents a shift from feature implementation to real-world validation. We will gather feedback from:

Dogfooding Integration - The project's own GitHub Pages landing site (crates/site) is end-to-end tested by playwright-rust itself (crates/site-e2e) as the deploy gate. Several Playwright-1.60 features (screenshot options including mask, Locator::drop, HAR recording, page-level ARIA snapshot) were surfaced and validated through this dogfooding loop.
Early Adopters - Community users trying v0.6.0+
Performance Metrics - Real-world performance data
Migration Experiences - Actual challenges when moving from other libraries

This feedback-driven approach ensures we're solving real problems, not theoretical ones.

Deferred from Version 0.6

High Priority

Examples and Migration Guide (Version 0.6 Slice 5)
- Why Deferred: Need real-world usage patterns to create meaningful examples
- Will Include:
  - Advanced examples addressing common use cases discovered through dogfooding
  - Migration guides tackling actual pain points from users switching libraries
  - Getting Started tutorial refined from onboarding experiences
  - Troubleshooting guide based on real issues encountered
- Success Metric: Examples directly address top 5 user pain points
Flaky Test Improvements (Version 0.6 Slice 7)
- Why Deferred: Require real-world usage to determine if alternative approaches are needed
- Items:
  - test_no_zombie_processes: Timing-dependent zombie reaping varies by OS/load. May need different approach to verify process cleanup without timing races.
  - test_error_recovery_stress: Rapid navigation success rate varies by CI environment. Consider alternative stress test that doesn't depend on navigation success rates.
- Context: Both tests verify important properties but can't guarantee 100% CI reliability due to environmental variance. Currently marked #[ignore] but available for manual validation.
- Success Metric: Either stabilize for CI or replace with reliable alternatives

Medium Priority

Performance Optimizations (Informed by real usage)
- Profile actual bottlenecks from dogfooding project
- Optimize based on real performance data, not assumptions
- May include deferred items from Version 0.6 if they prove important:
  - GUID string optimization
  - Transport chunked reading
  - Optimize tests (similar to Version 0.6, Slice 6d)
API Enhancements (Moved to Version 0.8)
- FilePayload struct
- BrowserContext options
- Route continue overrides

Version 1.0 Slices

Slice 0: Single-Crate Architecture Consolidation (Completed in v0.7.0)

Status: ✅ COMPLETED

Note: This work was completed as Version 0.7.0. See v0.7 Release Notes for details.

Slice 1: Dogfooding & Validation

Goal: Validate playwright-rust by dogfooding it on the project's own landing site (crates/site, gated by crates/site-e2e); document pain points and surface missing API surface.

Tasks:

Dogfooding project: the GitHub Pages landing site (crates/site), whose deploy is gated by a playwright-rust end-to-end test (crates/site-e2e)
Document integration challenges
Identify missing features or rough edges — surfaced the remaining Playwright-1.60 API surface (screenshot options incl. mask, Locator::drop, HAR recording, page-level ARIA snapshot); tracked in v1.0-gap-analysis.md
Create list of needed examples
Performance profiling in real usage

Progress:

Resolved Issue #1: Headless mode control (Verified)
Resolved Issue #2: Browser.isConnected() (Implemented)
Resolved Issue #24: page.set_viewport_size() for responsive testing (Implemented)
Flaky stress tests remain environmentally variable (test_no_zombie_processes, test_error_recovery_stress), tracked in the flaky-test issue #100. The cross-browser context stress flake (#99) was fixed on 2026-06-07 by splitting it into one test per engine so each browser launch gets its own timeout budget.

Iterative Workflow: This slice follows a feedback loop with the dogfooding project:

Identify: Attempt to implement user stories in the project until a blocker/pain point is hit.
Resolve: Switch to playwright-rust to resolve the specific issue (e.g., missing feature, bug).
Repeat: Return to project and continue until the user story is complete.
Finalize: Once integration is stable, complete the remaining documentation and profiling tasks.

Success Criteria:

Project successfully using playwright-rust in production
Pain points documented and prioritized
Performance baseline established

Slice 2: Community Feedback Analysis

Goal: Gather and analyze technical feedback from v0.7/v0.8 early adopters

Tasks:

Collect bug reports and feature requests
Identify common integration challenges
Analyze usage patterns and pain points
Prioritize fixes and enhancements

Success Criteria:

Clear list of technical issues to address
Prioritized feature backlog
Understanding of real-world usage patterns

Slice 3: Examples and Documentation (Informed by Feedback)

Goal: Create practical examples and guides based on real usage

Tasks:

Create examples addressing top use cases from dogfooding
Write migration guides for actual migration paths users took
Develop troubleshooting guide for common issues
Create cookbook-style examples for complex scenarios

Success Criteria:

Examples directly solve real user problems
Migration guides address actual pain points
Clear documentation for common patterns

Slice 4: Performance Optimization (Data-Driven)

Goal: Optimize based on real-world performance data

Tasks:

Analyze performance data from real usage
Profile memory usage in long-running applications
Optimize hot paths identified through profiling
Implement caching where beneficial
Consider async optimizations

Success Criteria:

20% performance improvement in common operations
Memory usage stable in long-running applications
No performance regressions

Slice 5: API Polish (Moved to v0.7/v0.8)

Status: ➡️ COMPLETE

Note: API polish and enhancements were implemented in v0.7 (Single Crate) and v0.8 (Remote Connection/DX).

Slice 6: v1.0.0 Release Preparation

Goal: Prepare and release stable v1.0.0 after real-world validation

Note: This comes AFTER v0.7/v0.8 foundations have been validated through Slices 1-5

Prerequisites:

v0.8.x released and validated
Community feedback incorporated
Performance optimized
Examples complete

Tasks:

Success Criteria:

API stable with no planned breaking changes
Security and license approved
v1.0.0 published and announced
Positive community reception
Dogfooding projects running on v1.0.0 in production
Clear commitment to semver stability going forward

Technical Success Metrics

Quality Metrics

< 5 critical bugs in production use
95% API stability (minimal breaking changes)
Performance within 10% of playwright-python
Zero memory leaks in long-running applications
Clean resource cleanup in all scenarios

Implementation Metrics

Dogfooding integration working smoothly
All deferred features implemented based on need
Test coverage maintained above 80%
Documentation answers 90% of user questions

Key Technical Decisions

API Stability - Which APIs to mark as stable vs experimental
Performance Trade-offs - Where to optimize vs maintain simplicity
Feature Scope - Which deferred features are actually needed
Breaking Changes - What changes justify a major version bump

Technical Risks and Mitigations

Risk	Impact	Mitigation
Major bugs discovered in production	Delays v1.0.0	Thorough testing in dogfooding project first
API changes needed	Breaking changes	Early validation, deprecation strategy
Performance issues	Poor user experience	Profile early and often
Platform-specific bugs	Limited adoption	Test on all platforms regularly

Notes

Architectural Discovery

Issue #3 Impact: During initial real-world validation integration, we discovered that the build script in playwright-core couldn't correctly determine workspace root when used as a crates.io dependency. This revealed fundamental architectural complexity in the two-crate split.

Decision Process:

Fixed issue #3 in v0.6.1 with robust workspace detection (interim solution)
Analyzed root cause → two-crate split adds complexity without value
Researched all official Playwright implementations → ALL use single packages
Created ADR 0003 documenting analysis and decision
Integrated consolidation into Version 0.7 (Slice 0)

This is exactly the type of discovery Version 1.0 was designed for: real-world usage revealing architectural issues that theoretical planning missed.

Implementation Approach

Trunk-based development: Small, frequent commits directly to main
CI validation: Every commit must pass full test suite
Real-world testing: Validate in dogfooding project throughout process
No long-lived branches: Changes integrated continuously

Plan Evolution

This plan evolved based on actual integration discoveries
Slices may continue to evolve based on technical priorities
Focus remains on solving real problems, not theoretical ones

Created: 2025-11-10 Last Updated: 2026-06-07 (Named the landing site as the dogfooding project; corrected flaky-test status)

Note: This is the high-level strategic plan for v1.0. The detailed, live API parity tracking (including the Playwright-1.60 "v0.14.0 completeness" work) lives in v1.0-gap-analysis.md.