playwright_rs/lib.rs
1//! playwright: High-level Rust bindings for Microsoft Playwright
2//!
3//! This crate provides the public API for browser automation using Playwright.
4//!
5//! # Examples
6//!
7//! ## Basic Navigation and Interaction
8//!
9//! ```ignore
10//! use playwright_rs::{Playwright, SelectOption};
11//!
12//! #[tokio::main]
13//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
14//! let playwright = Playwright::launch().await?;
15//! let browser = playwright.chromium().launch().await?;
16//! let page = browser.new_page().await?;
17//!
18//! // Navigate using data URL for self-contained test
19//! let _ = page.goto(
20//! "data:text/html,<html><body>\
21//! <h1 id='title'>Welcome</h1>\
22//! <button id='btn' onclick='this.textContent=\"Clicked\"'>Click me</button>\
23//! </body></html>",
24//! None
25//! ).await;
26//!
27//! // Query elements with locators
28//! let heading = page.locator("#title").await;
29//! let text = heading.text_content().await?;
30//! assert_eq!(text, Some("Welcome".to_string()));
31//!
32//! // Click button and verify result
33//! let button = page.locator("#btn").await;
34//! button.click(None).await?;
35//! let button_text = button.text_content().await?;
36//! assert_eq!(button_text, Some("Clicked".to_string()));
37//!
38//! browser.close().await?;
39//! Ok(())
40//! }
41//! ```
42//!
43//! ## Form Interaction
44//!
45//! ```ignore
46//! use playwright_rs::{Playwright, SelectOption};
47//!
48//! #[tokio::main]
49//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
50//! let playwright = Playwright::launch().await?;
51//! let browser = playwright.chromium().launch().await?;
52//! let page = browser.new_page().await?;
53//!
54//! // Create form with data URL
55//! let _ = page.goto(
56//! "data:text/html,<html><body>\
57//! <input type='text' id='name' />\
58//! <input type='checkbox' id='agree' />\
59//! <select id='country'>\
60//! <option value='us'>USA</option>\
61//! <option value='uk'>UK</option>\
62//! <option value='ca'>Canada</option>\
63//! </select>\
64//! </body></html>",
65//! None
66//! ).await;
67//!
68//! // Fill text input
69//! let name = page.locator("#name").await;
70//! name.fill("John Doe", None).await?;
71//! assert_eq!(name.input_value(None).await?, "John Doe");
72//!
73//! // Check checkbox
74//! let checkbox = page.locator("#agree").await;
75//! checkbox.set_checked(true, None).await?;
76//! assert!(checkbox.is_checked().await?);
77//!
78//! // Select option
79//! let select = page.locator("#country").await;
80//! select.select_option("uk", None).await?;
81//! assert_eq!(select.input_value(None).await?, "uk");
82//!
83//! browser.close().await?;
84//! Ok(())
85//! }
86//! ```
87//!
88//! ## Element Screenshots
89//!
90//! ```ignore
91//! use playwright_rs::Playwright;
92//!
93//! #[tokio::main]
94//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
95//! let playwright = Playwright::launch().await?;
96//! let browser = playwright.chromium().launch().await?;
97//! let page = browser.new_page().await?;
98//!
99//! // Create element to screenshot
100//! let _ = page.goto(
101//! "data:text/html,<html><body>\
102//! <div id='box' style='width:100px;height:100px;background:blue'></div>\
103//! </body></html>",
104//! None
105//! ).await;
106//!
107//! // Take screenshot of specific element
108//! let element = page.locator("#box").await;
109//! let screenshot = element.screenshot(None).await?;
110//! assert!(!screenshot.is_empty());
111//!
112//! browser.close().await?;
113//! Ok(())
114//! }
115//! ```
116//!
117//! ## Assertions (expect API)
118//!
119//! ```ignore
120//! use playwright_rs::{expect, Playwright};
121//!
122//! #[tokio::main]
123//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
124//! let playwright = Playwright::launch().await?;
125//! let browser = playwright.chromium().launch().await?;
126//! let page = browser.new_page().await?;
127//!
128//! let _ = page.goto(
129//! "data:text/html,<html><body>\
130//! <button id='enabled'>Enabled</button>\
131//! <button id='disabled' disabled>Disabled</button>\
132//! <input type='checkbox' id='checked' checked />\
133//! </body></html>",
134//! None
135//! ).await;
136//!
137//! // Assert button states with auto-retry
138//! let enabled_btn = page.locator("#enabled").await;
139//! expect(enabled_btn.clone()).to_be_enabled().await?;
140//!
141//! let disabled_btn = page.locator("#disabled").await;
142//! expect(disabled_btn).to_be_disabled().await?;
143//!
144//! // Assert checkbox state
145//! let checkbox = page.locator("#checked").await;
146//! expect(checkbox).to_be_checked().await?;
147//!
148//! browser.close().await?;
149//! Ok(())
150//! }
151//! ```
152
153// Internal modules (exposed for integration tests)
154#[doc(hidden)]
155pub mod server;
156
157pub mod api;
158mod assertions;
159mod error;
160pub mod protocol;
161
162/// Playwright server version bundled with this crate.
163///
164/// This version determines which browser builds are compatible.
165/// When installing browsers, use this version to ensure compatibility:
166///
167/// ```bash
168/// npx playwright@1.58.2 install
169/// ```
170///
171/// See: <https://playwright.dev/docs/browsers>
172pub const PLAYWRIGHT_VERSION: &str = env!("PLAYWRIGHT_DRIVER_VERSION");
173
174/// Default timeout in milliseconds for Playwright operations.
175///
176/// This matches Playwright's standard default across all language implementations (Python, Java, .NET, JS).
177/// Required in Playwright 1.56.1+ when timeout parameter is not explicitly provided.
178///
179/// See: <https://playwright.dev/docs/test-timeouts>
180pub const DEFAULT_TIMEOUT_MS: f64 = 30000.0;
181
182// Re-export error types
183pub use error::{Error, Result};
184
185// Re-export assertions API
186pub use assertions::{
187 Animations, PageExpectation, ScreenshotAssertionOptions, ScreenshotAssertionOptionsBuilder,
188 expect, expect_page,
189};
190
191// Re-export Playwright main entry point and browser API
192pub use protocol::{Browser, BrowserContext, BrowserType, HeaderEntry, Page, Playwright, Response};
193
194// Re-export Request and related types
195pub use protocol::{Request, ResourceTiming};
196
197// Re-export Locator and element APIs
198pub use protocol::{
199 AriaRole, BoundingBox, ElementHandle, FilterOptions, GetByRoleOptions, Locator,
200};
201
202// Re-export navigation and page options
203pub use protocol::{GotoOptions, WaitUntil};
204
205// Re-export action options
206pub use protocol::{
207 CheckOptions, ClickOptions, DragToOptions, FillOptions, HoverOptions, PressOptions,
208 PressSequentiallyOptions, SelectOptions, TapOptions, WaitForOptions, WaitForState,
209};
210
211// Re-export Position (needed for DragToOptions and other options)
212pub use protocol::Position;
213
214// Re-export form and input types
215pub use protocol::{FilePayload, SelectOption};
216
217// Re-export screenshot types
218pub use protocol::{ScreenshotClip, ScreenshotOptions, ScreenshotType};
219
220// Re-export new page method types
221pub use protocol::{
222 AddScriptTagOptions, ColorScheme, EmulateMediaOptions, ForcedColors, Media, PdfMargin,
223 PdfOptions, ReducedMotion,
224};
225
226// Re-export browser context options and storage state types
227pub use protocol::{
228 BrowserContextOptions, Cookie, Geolocation, LocalStorageItem, Origin, RecordHar, RecordVideo,
229 StorageState, Viewport,
230};
231
232// Re-export routing types
233pub use protocol::{FetchOptions, FetchResponse, FulfillOptions, Route, UnrouteBehavior};
234
235// Re-export launch and connection options
236pub use api::{ConnectOverCdpOptions, LaunchOptions};