playwright_rs_trace/
lib.rs

1//! Programmatic parser for [Playwright][pw] trace zip files
2//! (format v8, matching Playwright 1.59.x).
3//!
4//! # When to reach for this crate
5//!
6//! Pairs with the producer side, `playwright-rs::Tracing` (which
7//! writes `.trace.zip` files during a test run). This crate is the
8//! consumer side: a streaming, no-Playwright-server-required parser
9//! for those files. Typical users:
10//!
11//! - CI bots that comment on PRs with "test X failed at this Locator"
12//! - Dashboards that aggregate flaky-test root causes across runs
13//! - AI agent feedback loops that learn from past trace failures
14//! - Post-mortem analyzers run from a Rust binary or `xtask`
15//!
16//! No runtime dependency on the main `playwright-rs` crate — pull in
17//! only this crate (typically as a `[dev-dependencies]` entry) when
18//! you want to read traces.
19//!
20//! # Quick example
21//!
22//! ```rust,ignore
23//! use playwright_rs_trace::{open, TraceEvent};
24//!
25//! let mut reader = open("trace.zip")?;
26//! println!(
27//!     "trace v{} from {}",
28//!     reader.context().version,
29//!     reader.context().browser_name,
30//! );
31//!
32//! for action in reader.actions()? {
33//!     let action = action?;
34//!     if action.error.is_some() {
35//!         eprintln!(
36//!             "failed: {}.{} ({:?})",
37//!             action.class, action.method, action.error,
38//!         );
39//!     }
40//! }
41//! # Ok::<(), playwright_rs_trace::TraceError>(())
42//! ```
43//!
44//! The reader is a **streaming iterator** — events / actions are yielded
45//! lazily as the underlying zip stream is read, so a large trace
46//! doesn't need to fit in memory before processing begins.
47//!
48//! # Four streaming entry points on [`TraceReader`]
49//!
50//! - [`raw_events`] — every JSONL line as raw JSON. Forward-compat
51//!   escape hatch for callers dispatching on event kinds we don't
52//!   model.
53//! - [`events`] — same lines parsed into a typed [`TraceEvent`] enum.
54//!   Unknown / future kinds surface as [`TraceEvent::Unknown`].
55//! - [`actions`] — `before` + optional `input` + zero-or-more `log` +
56//!   `after` chunks reassembled into a logical [`Action`]. The common
57//!   case; use this unless you specifically need the raw event stream.
58//! - [`network`] — `NetworkEntry`s from the `trace.network` HAR-shape
59//!   stream (request / response pairs). Independent of the action
60//!   stream — collect-and-sort if you need a merged chronological
61//!   view.
62//!
63//! [`raw_events`]: TraceReader::raw_events
64//! [`events`]: TraceReader::events
65//! [`actions`]: TraceReader::actions
66//! [`network`]: TraceReader::network
67//!
68//! # Forward compatibility
69//!
70//! Every JSONL line is preserved losslessly via
71//! [`TraceReader::raw_events`]. The typed iterators
72//! ([`TraceReader::events`], [`TraceReader::actions`]) deserialize what
73//! the parser models and route anything else to
74//! [`TraceEvent::Unknown`] so nothing is silently dropped.
75//!
76//! See the crate `README.md` for the full slice-plan and roadmap.
77//!
78//! [pw]: https://playwright.dev/
79
80mod action;
81mod error;
82mod event;
83mod jsonl;
84mod network;
85mod trace;
86
87pub use action::{Action, ActionStream, LogLine};
88pub use error::{Result, TraceError};
89pub use event::{
90    ActionError, AfterEvent, BeforeEvent, ConsoleEvent, ConsoleLocation, ContextOptions,
91    FrameSnapshotEvent, InputEvent, LogEvent, Point, RawEvent, ResourceOverride,
92    ScreencastFrameEvent, SystemEvent, TraceEvent, Viewport,
93};
94pub use network::{
95    HeaderEntry, NetworkEntry, RequestPostData, RequestSnapshot, ResponseContent, ResponseSnapshot,
96};
97pub use trace::{TraceReader, open};
playwright_rs_trace/lib.rs

playwright_rs_trace/
lib.rs
