playwright_rs/
assertions.rs

1// Assertions - Auto-retry assertions for testing
2//
3// Provides expect() API with auto-retry logic matching Playwright's assertions.
4//
5// See: https://playwright.dev/docs/test-assertions
6
7use crate::error::Result;
8use crate::protocol::{Locator, Page};
9use std::path::Path;
10use std::time::Duration;
11
12/// Default timeout for assertions (5 seconds, matching Playwright)
13const DEFAULT_ASSERTION_TIMEOUT: Duration = Duration::from_secs(5);
14
15/// Default polling interval for assertions (100ms)
16const DEFAULT_POLL_INTERVAL: Duration = Duration::from_millis(100);
17
18/// Creates an expectation for a locator with auto-retry behavior.
19///
20/// Assertions will retry until they pass or timeout (default: 5 seconds).
21///
22/// # Example
23///
24/// ```ignore
25/// use playwright_rs::{expect, protocol::Playwright};
26/// use std::time::Duration;
27///
28/// #[tokio::main]
29/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
30///     let playwright = Playwright::launch().await?;
31///     let browser = playwright.chromium().launch().await?;
32///     let page = browser.new_page().await?;
33///
34///     // Test to_be_visible and to_be_hidden
35///     page.goto("data:text/html,<button id='btn'>Click me</button><div id='hidden' style='display:none'>Hidden</div>", None).await?;
36///     expect(page.locator("#btn").await).to_be_visible().await?;
37///     expect(page.locator("#hidden").await).to_be_hidden().await?;
38///
39///     // Test not() negation
40///     expect(page.locator("#btn").await).not().to_be_hidden().await?;
41///     expect(page.locator("#hidden").await).not().to_be_visible().await?;
42///
43///     // Test with_timeout()
44///     page.goto("data:text/html,<div id='element'>Visible</div>", None).await?;
45///     expect(page.locator("#element").await)
46///         .with_timeout(Duration::from_secs(10))
47///         .to_be_visible()
48///         .await?;
49///
50///     // Test to_be_enabled and to_be_disabled
51///     page.goto("data:text/html,<button id='enabled'>Enabled</button><button id='disabled' disabled>Disabled</button>", None).await?;
52///     expect(page.locator("#enabled").await).to_be_enabled().await?;
53///     expect(page.locator("#disabled").await).to_be_disabled().await?;
54///
55///     // Test to_be_checked and to_be_unchecked
56///     page.goto("data:text/html,<input type='checkbox' id='checked' checked><input type='checkbox' id='unchecked'>", None).await?;
57///     expect(page.locator("#checked").await).to_be_checked().await?;
58///     expect(page.locator("#unchecked").await).to_be_unchecked().await?;
59///
60///     // Test to_be_editable
61///     page.goto("data:text/html,<input type='text' id='editable'>", None).await?;
62///     expect(page.locator("#editable").await).to_be_editable().await?;
63///
64///     // Test to_be_focused
65///     page.goto("data:text/html,<input type='text' id='input'>", None).await?;
66///     page.evaluate::<(), ()>("document.getElementById('input').focus()", None).await?;
67///     expect(page.locator("#input").await).to_be_focused().await?;
68///
69///     // Test to_contain_text
70///     page.goto("data:text/html,<div id='content'>Hello World</div>", None).await?;
71///     expect(page.locator("#content").await).to_contain_text("Hello").await?;
72///     expect(page.locator("#content").await).to_contain_text("World").await?;
73///
74///     // Test to_have_text
75///     expect(page.locator("#content").await).to_have_text("Hello World").await?;
76///
77///     // Test to_have_value
78///     page.goto("data:text/html,<input type='text' id='input' value='test value'>", None).await?;
79///     expect(page.locator("#input").await).to_have_value("test value").await?;
80///
81///     browser.close().await?;
82///     Ok(())
83/// }
84/// ```
85///
86/// See: <https://playwright.dev/docs/test-assertions>
87pub fn expect(locator: Locator) -> Expectation {
88    Expectation::new(locator)
89}
90
91/// Expectation wraps a locator and provides assertion methods with auto-retry.
92pub struct Expectation {
93    locator: Locator,
94    timeout: Duration,
95    poll_interval: Duration,
96    negate: bool,
97}
98
99// Allow clippy::wrong_self_convention for to_* methods that consume self
100// This matches Playwright's expect API pattern where assertions are chained and consumed
101#[allow(clippy::wrong_self_convention)]
102impl Expectation {
103    /// Creates a new expectation for the given locator.
104    pub(crate) fn new(locator: Locator) -> Self {
105        Self {
106            locator,
107            timeout: DEFAULT_ASSERTION_TIMEOUT,
108            poll_interval: DEFAULT_POLL_INTERVAL,
109            negate: false,
110        }
111    }
112
113    /// Sets a custom timeout for this assertion.
114    ///
115    pub fn with_timeout(mut self, timeout: Duration) -> Self {
116        self.timeout = timeout;
117        self
118    }
119
120    /// Sets a custom poll interval for this assertion.
121    ///
122    /// Default is 100ms.
123    pub fn with_poll_interval(mut self, interval: Duration) -> Self {
124        self.poll_interval = interval;
125        self
126    }
127
128    /// Negates the assertion.
129    ///
130    /// Note: We intentionally use `.not()` method instead of implementing `std::ops::Not`
131    /// to match Playwright's API across all language bindings (JS/Python/Java/.NET).
132    #[allow(clippy::should_implement_trait)]
133    pub fn not(mut self) -> Self {
134        self.negate = true;
135        self
136    }
137
138    /// Asserts that the element is visible.
139    ///
140    /// This assertion will retry until the element becomes visible or timeout.
141    ///
142    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-visible>
143    pub async fn to_be_visible(self) -> Result<()> {
144        let start = std::time::Instant::now();
145        let selector = self.locator.selector().to_string();
146
147        loop {
148            let is_visible = self.locator.is_visible().await?;
149
150            // Check if condition matches (with negation support)
151            let matches = if self.negate { !is_visible } else { is_visible };
152
153            if matches {
154                return Ok(());
155            }
156
157            // Check timeout
158            if start.elapsed() >= self.timeout {
159                let message = if self.negate {
160                    format!(
161                        "Expected element '{}' NOT to be visible, but it was visible after {:?}",
162                        selector, self.timeout
163                    )
164                } else {
165                    format!(
166                        "Expected element '{}' to be visible, but it was not visible after {:?}",
167                        selector, self.timeout
168                    )
169                };
170                return Err(crate::error::Error::AssertionTimeout(message));
171            }
172
173            // Wait before next poll
174            tokio::time::sleep(self.poll_interval).await;
175        }
176    }
177
178    /// Asserts that the element is hidden (not visible).
179    ///
180    /// This assertion will retry until the element becomes hidden or timeout.
181    ///
182    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-hidden>
183    pub async fn to_be_hidden(self) -> Result<()> {
184        // to_be_hidden is the opposite of to_be_visible
185        // Use negation to reuse the visibility logic
186        let negated = Expectation {
187            negate: !self.negate, // Flip negation
188            ..self
189        };
190        negated.to_be_visible().await
191    }
192
193    /// Asserts that the element has the specified text content (exact match).
194    ///
195    /// This assertion will retry until the element has the exact text or timeout.
196    /// Text is trimmed before comparison.
197    ///
198    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-have-text>
199    pub async fn to_have_text(self, expected: &str) -> Result<()> {
200        let start = std::time::Instant::now();
201        let selector = self.locator.selector().to_string();
202        let expected = expected.trim();
203
204        loop {
205            // Get text content (using inner_text for consistency with Playwright)
206            let actual_text = self.locator.inner_text().await?;
207            let actual = actual_text.trim();
208
209            // Check if condition matches (with negation support)
210            let matches = if self.negate {
211                actual != expected
212            } else {
213                actual == expected
214            };
215
216            if matches {
217                return Ok(());
218            }
219
220            // Check timeout
221            if start.elapsed() >= self.timeout {
222                let message = if self.negate {
223                    format!(
224                        "Expected element '{}' NOT to have text '{}', but it did after {:?}",
225                        selector, expected, self.timeout
226                    )
227                } else {
228                    format!(
229                        "Expected element '{}' to have text '{}', but had '{}' after {:?}",
230                        selector, expected, actual, self.timeout
231                    )
232                };
233                return Err(crate::error::Error::AssertionTimeout(message));
234            }
235
236            // Wait before next poll
237            tokio::time::sleep(self.poll_interval).await;
238        }
239    }
240
241    /// Asserts that the element's text matches the specified regex pattern.
242    ///
243    /// This assertion will retry until the element's text matches the pattern or timeout.
244    pub async fn to_have_text_regex(self, pattern: &str) -> Result<()> {
245        let start = std::time::Instant::now();
246        let selector = self.locator.selector().to_string();
247        let re = regex::Regex::new(pattern)
248            .map_err(|e| crate::error::Error::InvalidArgument(format!("Invalid regex: {}", e)))?;
249
250        loop {
251            let actual_text = self.locator.inner_text().await?;
252            let actual = actual_text.trim();
253
254            // Check if condition matches (with negation support)
255            let matches = if self.negate {
256                !re.is_match(actual)
257            } else {
258                re.is_match(actual)
259            };
260
261            if matches {
262                return Ok(());
263            }
264
265            // Check timeout
266            if start.elapsed() >= self.timeout {
267                let message = if self.negate {
268                    format!(
269                        "Expected element '{}' NOT to match pattern '{}', but it did after {:?}",
270                        selector, pattern, self.timeout
271                    )
272                } else {
273                    format!(
274                        "Expected element '{}' to match pattern '{}', but had '{}' after {:?}",
275                        selector, pattern, actual, self.timeout
276                    )
277                };
278                return Err(crate::error::Error::AssertionTimeout(message));
279            }
280
281            // Wait before next poll
282            tokio::time::sleep(self.poll_interval).await;
283        }
284    }
285
286    /// Asserts that the element contains the specified text (substring match).
287    ///
288    /// This assertion will retry until the element contains the text or timeout.
289    ///
290    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-contain-text>
291    pub async fn to_contain_text(self, expected: &str) -> Result<()> {
292        let start = std::time::Instant::now();
293        let selector = self.locator.selector().to_string();
294
295        loop {
296            let actual_text = self.locator.inner_text().await?;
297            let actual = actual_text.trim();
298
299            // Check if condition matches (with negation support)
300            let matches = if self.negate {
301                !actual.contains(expected)
302            } else {
303                actual.contains(expected)
304            };
305
306            if matches {
307                return Ok(());
308            }
309
310            // Check timeout
311            if start.elapsed() >= self.timeout {
312                let message = if self.negate {
313                    format!(
314                        "Expected element '{}' NOT to contain text '{}', but it did after {:?}",
315                        selector, expected, self.timeout
316                    )
317                } else {
318                    format!(
319                        "Expected element '{}' to contain text '{}', but had '{}' after {:?}",
320                        selector, expected, actual, self.timeout
321                    )
322                };
323                return Err(crate::error::Error::AssertionTimeout(message));
324            }
325
326            // Wait before next poll
327            tokio::time::sleep(self.poll_interval).await;
328        }
329    }
330
331    /// Asserts that the element's text contains a substring matching the regex pattern.
332    ///
333    /// This assertion will retry until the element contains the pattern or timeout.
334    pub async fn to_contain_text_regex(self, pattern: &str) -> Result<()> {
335        let start = std::time::Instant::now();
336        let selector = self.locator.selector().to_string();
337        let re = regex::Regex::new(pattern)
338            .map_err(|e| crate::error::Error::InvalidArgument(format!("Invalid regex: {}", e)))?;
339
340        loop {
341            let actual_text = self.locator.inner_text().await?;
342            let actual = actual_text.trim();
343
344            // Check if condition matches (with negation support)
345            let matches = if self.negate {
346                !re.is_match(actual)
347            } else {
348                re.is_match(actual)
349            };
350
351            if matches {
352                return Ok(());
353            }
354
355            // Check timeout
356            if start.elapsed() >= self.timeout {
357                let message = if self.negate {
358                    format!(
359                        "Expected element '{}' NOT to contain pattern '{}', but it did after {:?}",
360                        selector, pattern, self.timeout
361                    )
362                } else {
363                    format!(
364                        "Expected element '{}' to contain pattern '{}', but had '{}' after {:?}",
365                        selector, pattern, actual, self.timeout
366                    )
367                };
368                return Err(crate::error::Error::AssertionTimeout(message));
369            }
370
371            // Wait before next poll
372            tokio::time::sleep(self.poll_interval).await;
373        }
374    }
375
376    /// Asserts that the input element has the specified value.
377    ///
378    /// This assertion will retry until the input has the exact value or timeout.
379    ///
380    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-have-value>
381    pub async fn to_have_value(self, expected: &str) -> Result<()> {
382        let start = std::time::Instant::now();
383        let selector = self.locator.selector().to_string();
384
385        loop {
386            let actual = self.locator.input_value(None).await?;
387
388            // Check if condition matches (with negation support)
389            let matches = if self.negate {
390                actual != expected
391            } else {
392                actual == expected
393            };
394
395            if matches {
396                return Ok(());
397            }
398
399            // Check timeout
400            if start.elapsed() >= self.timeout {
401                let message = if self.negate {
402                    format!(
403                        "Expected input '{}' NOT to have value '{}', but it did after {:?}",
404                        selector, expected, self.timeout
405                    )
406                } else {
407                    format!(
408                        "Expected input '{}' to have value '{}', but had '{}' after {:?}",
409                        selector, expected, actual, self.timeout
410                    )
411                };
412                return Err(crate::error::Error::AssertionTimeout(message));
413            }
414
415            // Wait before next poll
416            tokio::time::sleep(self.poll_interval).await;
417        }
418    }
419
420    /// Asserts that the input element's value matches the specified regex pattern.
421    ///
422    /// This assertion will retry until the input value matches the pattern or timeout.
423    pub async fn to_have_value_regex(self, pattern: &str) -> Result<()> {
424        let start = std::time::Instant::now();
425        let selector = self.locator.selector().to_string();
426        let re = regex::Regex::new(pattern)
427            .map_err(|e| crate::error::Error::InvalidArgument(format!("Invalid regex: {}", e)))?;
428
429        loop {
430            let actual = self.locator.input_value(None).await?;
431
432            // Check if condition matches (with negation support)
433            let matches = if self.negate {
434                !re.is_match(&actual)
435            } else {
436                re.is_match(&actual)
437            };
438
439            if matches {
440                return Ok(());
441            }
442
443            // Check timeout
444            if start.elapsed() >= self.timeout {
445                let message = if self.negate {
446                    format!(
447                        "Expected input '{}' NOT to match pattern '{}', but it did after {:?}",
448                        selector, pattern, self.timeout
449                    )
450                } else {
451                    format!(
452                        "Expected input '{}' to match pattern '{}', but had '{}' after {:?}",
453                        selector, pattern, actual, self.timeout
454                    )
455                };
456                return Err(crate::error::Error::AssertionTimeout(message));
457            }
458
459            // Wait before next poll
460            tokio::time::sleep(self.poll_interval).await;
461        }
462    }
463
464    /// Asserts that the element is enabled.
465    ///
466    /// This assertion will retry until the element is enabled or timeout.
467    /// An element is enabled if it does not have the "disabled" attribute.
468    ///
469    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-enabled>
470    pub async fn to_be_enabled(self) -> Result<()> {
471        let start = std::time::Instant::now();
472        let selector = self.locator.selector().to_string();
473
474        loop {
475            let is_enabled = self.locator.is_enabled().await?;
476
477            // Check if condition matches (with negation support)
478            let matches = if self.negate { !is_enabled } else { is_enabled };
479
480            if matches {
481                return Ok(());
482            }
483
484            // Check timeout
485            if start.elapsed() >= self.timeout {
486                let message = if self.negate {
487                    format!(
488                        "Expected element '{}' NOT to be enabled, but it was enabled after {:?}",
489                        selector, self.timeout
490                    )
491                } else {
492                    format!(
493                        "Expected element '{}' to be enabled, but it was not enabled after {:?}",
494                        selector, self.timeout
495                    )
496                };
497                return Err(crate::error::Error::AssertionTimeout(message));
498            }
499
500            // Wait before next poll
501            tokio::time::sleep(self.poll_interval).await;
502        }
503    }
504
505    /// Asserts that the element is disabled.
506    ///
507    /// This assertion will retry until the element is disabled or timeout.
508    /// An element is disabled if it has the "disabled" attribute.
509    ///
510    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-disabled>
511    pub async fn to_be_disabled(self) -> Result<()> {
512        // to_be_disabled is the opposite of to_be_enabled
513        // Use negation to reuse the enabled logic
514        let negated = Expectation {
515            negate: !self.negate, // Flip negation
516            ..self
517        };
518        negated.to_be_enabled().await
519    }
520
521    /// Asserts that the checkbox or radio button is checked.
522    ///
523    /// This assertion will retry until the element is checked or timeout.
524    ///
525    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-checked>
526    pub async fn to_be_checked(self) -> Result<()> {
527        let start = std::time::Instant::now();
528        let selector = self.locator.selector().to_string();
529
530        loop {
531            let is_checked = self.locator.is_checked().await?;
532
533            // Check if condition matches (with negation support)
534            let matches = if self.negate { !is_checked } else { is_checked };
535
536            if matches {
537                return Ok(());
538            }
539
540            // Check timeout
541            if start.elapsed() >= self.timeout {
542                let message = if self.negate {
543                    format!(
544                        "Expected element '{}' NOT to be checked, but it was checked after {:?}",
545                        selector, self.timeout
546                    )
547                } else {
548                    format!(
549                        "Expected element '{}' to be checked, but it was not checked after {:?}",
550                        selector, self.timeout
551                    )
552                };
553                return Err(crate::error::Error::AssertionTimeout(message));
554            }
555
556            // Wait before next poll
557            tokio::time::sleep(self.poll_interval).await;
558        }
559    }
560
561    /// Asserts that the checkbox or radio button is unchecked.
562    ///
563    /// This assertion will retry until the element is unchecked or timeout.
564    ///
565    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-checked>
566    pub async fn to_be_unchecked(self) -> Result<()> {
567        // to_be_unchecked is the opposite of to_be_checked
568        // Use negation to reuse the checked logic
569        let negated = Expectation {
570            negate: !self.negate, // Flip negation
571            ..self
572        };
573        negated.to_be_checked().await
574    }
575
576    /// Asserts that the element is editable.
577    ///
578    /// This assertion will retry until the element is editable or timeout.
579    /// An element is editable if it is enabled and does not have the "readonly" attribute.
580    ///
581    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-editable>
582    pub async fn to_be_editable(self) -> Result<()> {
583        let start = std::time::Instant::now();
584        let selector = self.locator.selector().to_string();
585
586        loop {
587            let is_editable = self.locator.is_editable().await?;
588
589            // Check if condition matches (with negation support)
590            let matches = if self.negate {
591                !is_editable
592            } else {
593                is_editable
594            };
595
596            if matches {
597                return Ok(());
598            }
599
600            // Check timeout
601            if start.elapsed() >= self.timeout {
602                let message = if self.negate {
603                    format!(
604                        "Expected element '{}' NOT to be editable, but it was editable after {:?}",
605                        selector, self.timeout
606                    )
607                } else {
608                    format!(
609                        "Expected element '{}' to be editable, but it was not editable after {:?}",
610                        selector, self.timeout
611                    )
612                };
613                return Err(crate::error::Error::AssertionTimeout(message));
614            }
615
616            // Wait before next poll
617            tokio::time::sleep(self.poll_interval).await;
618        }
619    }
620
621    /// Asserts that the element is focused (currently has focus).
622    ///
623    /// This assertion will retry until the element becomes focused or timeout.
624    ///
625    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-be-focused>
626    pub async fn to_be_focused(self) -> Result<()> {
627        let start = std::time::Instant::now();
628        let selector = self.locator.selector().to_string();
629
630        loop {
631            let is_focused = self.locator.is_focused().await?;
632
633            // Check if condition matches (with negation support)
634            let matches = if self.negate { !is_focused } else { is_focused };
635
636            if matches {
637                return Ok(());
638            }
639
640            // Check timeout
641            if start.elapsed() >= self.timeout {
642                let message = if self.negate {
643                    format!(
644                        "Expected element '{}' NOT to be focused, but it was focused after {:?}",
645                        selector, self.timeout
646                    )
647                } else {
648                    format!(
649                        "Expected element '{}' to be focused, but it was not focused after {:?}",
650                        selector, self.timeout
651                    )
652                };
653                return Err(crate::error::Error::AssertionTimeout(message));
654            }
655
656            // Wait before next poll
657            tokio::time::sleep(self.poll_interval).await;
658        }
659    }
660
661    /// Asserts that a locator's screenshot matches a baseline image.
662    ///
663    /// On first run (no baseline file), saves the screenshot as the new baseline.
664    /// On subsequent runs, compares the screenshot pixel-by-pixel against the baseline.
665    ///
666    /// See: <https://playwright.dev/docs/test-assertions#locator-assertions-to-have-screenshot-1>
667    pub async fn to_have_screenshot(
668        self,
669        baseline_path: impl AsRef<Path>,
670        options: Option<ScreenshotAssertionOptions>,
671    ) -> Result<()> {
672        let opts = options.unwrap_or_default();
673        let baseline_path = baseline_path.as_ref();
674
675        // Disable animations if requested
676        if opts.animations == Some(Animations::Disabled) {
677            let _ = self
678                .locator
679                .evaluate_js(DISABLE_ANIMATIONS_JS, None::<&()>)
680                .await;
681        }
682
683        // Build screenshot options with mask support
684        let screenshot_opts = if let Some(ref mask_locators) = opts.mask {
685            // Inject mask overlays before capturing
686            let mask_js = build_mask_js(mask_locators);
687            let _ = self.locator.evaluate_js(&mask_js, None::<&()>).await;
688            None
689        } else {
690            None
691        };
692
693        compare_screenshot(
694            &opts,
695            baseline_path,
696            self.timeout,
697            self.poll_interval,
698            self.negate,
699            || async { self.locator.screenshot(screenshot_opts.clone()).await },
700        )
701        .await
702    }
703}
704
705/// CSS to disable all animations and transitions
706const DISABLE_ANIMATIONS_JS: &str = r#"
707(() => {
708    const style = document.createElement('style');
709    style.textContent = '*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; }';
710    style.setAttribute('data-playwright-no-animations', '');
711    document.head.appendChild(style);
712})()
713"#;
714
715/// Build JavaScript to overlay mask regions with pink (#FF00FF) rectangles
716fn build_mask_js(locators: &[Locator]) -> String {
717    let selectors: Vec<String> = locators
718        .iter()
719        .map(|l| {
720            let sel = l.selector().replace('\'', "\\'");
721            format!(
722                r#"
723                (function() {{
724                    var els = document.querySelectorAll('{}');
725                    els.forEach(function(el) {{
726                        var rect = el.getBoundingClientRect();
727                        var overlay = document.createElement('div');
728                        overlay.setAttribute('data-playwright-mask', '');
729                        overlay.style.cssText = 'position:fixed;z-index:2147483647;background:#FF00FF;pointer-events:none;'
730                            + 'left:' + rect.left + 'px;top:' + rect.top + 'px;width:' + rect.width + 'px;height:' + rect.height + 'px;';
731                        document.body.appendChild(overlay);
732                    }});
733                }})();
734                "#,
735                sel
736            )
737        })
738        .collect();
739    selectors.join("\n")
740}
741
742/// Animation control for screenshots
743///
744/// See: <https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1>
745#[derive(Debug, Clone, Copy, PartialEq, Eq)]
746pub enum Animations {
747    /// Allow animations to run normally
748    Allow,
749    /// Disable CSS animations and transitions before capturing
750    Disabled,
751}
752
753/// Options for screenshot assertions
754///
755/// See: <https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1>
756#[derive(Debug, Clone, Default)]
757pub struct ScreenshotAssertionOptions {
758    /// Maximum number of different pixels allowed (default: 0)
759    pub max_diff_pixels: Option<u32>,
760    /// Maximum ratio of different pixels (0.0 to 1.0)
761    pub max_diff_pixel_ratio: Option<f64>,
762    /// Per-pixel color distance threshold (0.0 to 1.0, default: 0.2)
763    pub threshold: Option<f64>,
764    /// Disable CSS animations before capturing
765    pub animations: Option<Animations>,
766    /// Locators to mask with pink (#FF00FF) overlay
767    pub mask: Option<Vec<Locator>>,
768    /// Force update baseline even if it exists
769    pub update_snapshots: Option<bool>,
770}
771
772impl ScreenshotAssertionOptions {
773    /// Create a new builder for ScreenshotAssertionOptions
774    pub fn builder() -> ScreenshotAssertionOptionsBuilder {
775        ScreenshotAssertionOptionsBuilder::default()
776    }
777}
778
779/// Builder for ScreenshotAssertionOptions
780#[derive(Debug, Clone, Default)]
781pub struct ScreenshotAssertionOptionsBuilder {
782    max_diff_pixels: Option<u32>,
783    max_diff_pixel_ratio: Option<f64>,
784    threshold: Option<f64>,
785    animations: Option<Animations>,
786    mask: Option<Vec<Locator>>,
787    update_snapshots: Option<bool>,
788}
789
790impl ScreenshotAssertionOptionsBuilder {
791    /// Maximum number of different pixels allowed
792    pub fn max_diff_pixels(mut self, pixels: u32) -> Self {
793        self.max_diff_pixels = Some(pixels);
794        self
795    }
796
797    /// Maximum ratio of different pixels (0.0 to 1.0)
798    pub fn max_diff_pixel_ratio(mut self, ratio: f64) -> Self {
799        self.max_diff_pixel_ratio = Some(ratio);
800        self
801    }
802
803    /// Per-pixel color distance threshold (0.0 to 1.0)
804    pub fn threshold(mut self, threshold: f64) -> Self {
805        self.threshold = Some(threshold);
806        self
807    }
808
809    /// Disable CSS animations and transitions before capturing
810    pub fn animations(mut self, animations: Animations) -> Self {
811        self.animations = Some(animations);
812        self
813    }
814
815    /// Locators to mask with pink (#FF00FF) overlay
816    pub fn mask(mut self, locators: Vec<Locator>) -> Self {
817        self.mask = Some(locators);
818        self
819    }
820
821    /// Force update baseline even if it exists
822    pub fn update_snapshots(mut self, update: bool) -> Self {
823        self.update_snapshots = Some(update);
824        self
825    }
826
827    /// Build the ScreenshotAssertionOptions
828    pub fn build(self) -> ScreenshotAssertionOptions {
829        ScreenshotAssertionOptions {
830            max_diff_pixels: self.max_diff_pixels,
831            max_diff_pixel_ratio: self.max_diff_pixel_ratio,
832            threshold: self.threshold,
833            animations: self.animations,
834            mask: self.mask,
835            update_snapshots: self.update_snapshots,
836        }
837    }
838}
839
840/// Creates a page-level expectation for screenshot assertions.
841///
842/// See: <https://playwright.dev/docs/test-assertions#page-assertions-to-have-screenshot-1>
843pub fn expect_page(page: &Page) -> PageExpectation {
844    PageExpectation::new(page.clone())
845}
846
847/// Page-level expectation for screenshot assertions.
848#[allow(clippy::wrong_self_convention)]
849pub struct PageExpectation {
850    page: Page,
851    timeout: Duration,
852    poll_interval: Duration,
853    negate: bool,
854}
855
856impl PageExpectation {
857    fn new(page: Page) -> Self {
858        Self {
859            page,
860            timeout: DEFAULT_ASSERTION_TIMEOUT,
861            poll_interval: DEFAULT_POLL_INTERVAL,
862            negate: false,
863        }
864    }
865
866    /// Sets a custom timeout for this assertion.
867    pub fn with_timeout(mut self, timeout: Duration) -> Self {
868        self.timeout = timeout;
869        self
870    }
871
872    /// Negates the assertion.
873    #[allow(clippy::should_implement_trait)]
874    pub fn not(mut self) -> Self {
875        self.negate = true;
876        self
877    }
878
879    /// Asserts that the page screenshot matches a baseline image.
880    ///
881    /// See: <https://playwright.dev/docs/test-assertions#page-assertions-to-have-screenshot-1>
882    pub async fn to_have_screenshot(
883        self,
884        baseline_path: impl AsRef<Path>,
885        options: Option<ScreenshotAssertionOptions>,
886    ) -> Result<()> {
887        let opts = options.unwrap_or_default();
888        let baseline_path = baseline_path.as_ref();
889
890        // Disable animations if requested
891        if opts.animations == Some(Animations::Disabled) {
892            let _ = self.page.evaluate_expression(DISABLE_ANIMATIONS_JS).await;
893        }
894
895        // Inject mask overlays if specified
896        if let Some(ref mask_locators) = opts.mask {
897            let mask_js = build_mask_js(mask_locators);
898            let _ = self.page.evaluate_expression(&mask_js).await;
899        }
900
901        compare_screenshot(
902            &opts,
903            baseline_path,
904            self.timeout,
905            self.poll_interval,
906            self.negate,
907            || async { self.page.screenshot(None).await },
908        )
909        .await
910    }
911}
912
913/// Core screenshot comparison logic shared by Locator and Page assertions.
914async fn compare_screenshot<F, Fut>(
915    opts: &ScreenshotAssertionOptions,
916    baseline_path: &Path,
917    timeout: Duration,
918    poll_interval: Duration,
919    negate: bool,
920    take_screenshot: F,
921) -> Result<()>
922where
923    F: Fn() -> Fut,
924    Fut: std::future::Future<Output = Result<Vec<u8>>>,
925{
926    let threshold = opts.threshold.unwrap_or(0.2);
927    let max_diff_pixels = opts.max_diff_pixels;
928    let max_diff_pixel_ratio = opts.max_diff_pixel_ratio;
929    let update_snapshots = opts.update_snapshots.unwrap_or(false);
930
931    // Take initial screenshot
932    let actual_bytes = take_screenshot().await?;
933
934    // If baseline doesn't exist or update_snapshots is set, save and return
935    if !baseline_path.exists() || update_snapshots {
936        if let Some(parent) = baseline_path.parent() {
937            tokio::fs::create_dir_all(parent).await.map_err(|e| {
938                crate::error::Error::ProtocolError(format!(
939                    "Failed to create baseline directory: {}",
940                    e
941                ))
942            })?;
943        }
944        tokio::fs::write(baseline_path, &actual_bytes)
945            .await
946            .map_err(|e| {
947                crate::error::Error::ProtocolError(format!(
948                    "Failed to write baseline screenshot: {}",
949                    e
950                ))
951            })?;
952        return Ok(());
953    }
954
955    // Load baseline
956    let baseline_bytes = tokio::fs::read(baseline_path).await.map_err(|e| {
957        crate::error::Error::ProtocolError(format!("Failed to read baseline screenshot: {}", e))
958    })?;
959
960    let start = std::time::Instant::now();
961
962    loop {
963        let screenshot_bytes = if start.elapsed().is_zero() {
964            actual_bytes.clone()
965        } else {
966            take_screenshot().await?
967        };
968
969        let comparison = compare_images(&baseline_bytes, &screenshot_bytes, threshold)?;
970
971        let within_tolerance =
972            is_within_tolerance(&comparison, max_diff_pixels, max_diff_pixel_ratio);
973
974        let matches = if negate {
975            !within_tolerance
976        } else {
977            within_tolerance
978        };
979
980        if matches {
981            return Ok(());
982        }
983
984        if start.elapsed() >= timeout {
985            if negate {
986                return Err(crate::error::Error::AssertionTimeout(format!(
987                    "Expected screenshots NOT to match, but they matched after {:?}",
988                    timeout
989                )));
990            }
991
992            // Save actual and diff images for debugging
993            let baseline_stem = baseline_path
994                .file_stem()
995                .and_then(|s| s.to_str())
996                .unwrap_or("screenshot");
997            let baseline_ext = baseline_path
998                .extension()
999                .and_then(|s| s.to_str())
1000                .unwrap_or("png");
1001            let baseline_dir = baseline_path.parent().unwrap_or(Path::new("."));
1002
1003            let actual_path =
1004                baseline_dir.join(format!("{}-actual.{}", baseline_stem, baseline_ext));
1005            let diff_path = baseline_dir.join(format!("{}-diff.{}", baseline_stem, baseline_ext));
1006
1007            let _ = tokio::fs::write(&actual_path, &screenshot_bytes).await;
1008
1009            if let Ok(diff_bytes) =
1010                generate_diff_image(&baseline_bytes, &screenshot_bytes, threshold)
1011            {
1012                let _ = tokio::fs::write(&diff_path, diff_bytes).await;
1013            }
1014
1015            return Err(crate::error::Error::AssertionTimeout(format!(
1016                "Screenshot mismatch: {} pixels differ ({:.2}% of total). \
1017                 Max allowed: {}. Threshold: {:.2}. \
1018                 Actual saved to: {}. Diff saved to: {}. \
1019                 Timed out after {:?}",
1020                comparison.diff_count,
1021                comparison.diff_ratio * 100.0,
1022                max_diff_pixels
1023                    .map(|p| p.to_string())
1024                    .or_else(|| max_diff_pixel_ratio.map(|r| format!("{:.2}%", r * 100.0)))
1025                    .unwrap_or_else(|| "0".to_string()),
1026                threshold,
1027                actual_path.display(),
1028                diff_path.display(),
1029                timeout,
1030            )));
1031        }
1032
1033        tokio::time::sleep(poll_interval).await;
1034    }
1035}
1036
1037/// Result of comparing two images pixel-by-pixel
1038struct ImageComparison {
1039    diff_count: u32,
1040    diff_ratio: f64,
1041}
1042
1043fn is_within_tolerance(
1044    comparison: &ImageComparison,
1045    max_diff_pixels: Option<u32>,
1046    max_diff_pixel_ratio: Option<f64>,
1047) -> bool {
1048    if let Some(max_pixels) = max_diff_pixels {
1049        if comparison.diff_count > max_pixels {
1050            return false;
1051        }
1052    } else if let Some(max_ratio) = max_diff_pixel_ratio {
1053        if comparison.diff_ratio > max_ratio {
1054            return false;
1055        }
1056    } else {
1057        // No tolerance specified — require exact match
1058        if comparison.diff_count > 0 {
1059            return false;
1060        }
1061    }
1062    true
1063}
1064
1065/// Compare two PNG images pixel-by-pixel with a color distance threshold
1066fn compare_images(
1067    baseline_bytes: &[u8],
1068    actual_bytes: &[u8],
1069    threshold: f64,
1070) -> Result<ImageComparison> {
1071    use image::GenericImageView;
1072
1073    let baseline_img = image::load_from_memory(baseline_bytes).map_err(|e| {
1074        crate::error::Error::ProtocolError(format!("Failed to decode baseline image: {}", e))
1075    })?;
1076    let actual_img = image::load_from_memory(actual_bytes).map_err(|e| {
1077        crate::error::Error::ProtocolError(format!("Failed to decode actual image: {}", e))
1078    })?;
1079
1080    let (bw, bh) = baseline_img.dimensions();
1081    let (aw, ah) = actual_img.dimensions();
1082
1083    // Different dimensions = all pixels differ
1084    if bw != aw || bh != ah {
1085        let total = bw.max(aw) * bh.max(ah);
1086        return Ok(ImageComparison {
1087            diff_count: total,
1088            diff_ratio: 1.0,
1089        });
1090    }
1091
1092    let total_pixels = bw * bh;
1093    if total_pixels == 0 {
1094        return Ok(ImageComparison {
1095            diff_count: 0,
1096            diff_ratio: 0.0,
1097        });
1098    }
1099
1100    let threshold_sq = threshold * threshold;
1101    let mut diff_count: u32 = 0;
1102
1103    for y in 0..bh {
1104        for x in 0..bw {
1105            let bp = baseline_img.get_pixel(x, y);
1106            let ap = actual_img.get_pixel(x, y);
1107
1108            // Compute normalized color distance (each channel 0.0-1.0)
1109            let dr = (bp[0] as f64 - ap[0] as f64) / 255.0;
1110            let dg = (bp[1] as f64 - ap[1] as f64) / 255.0;
1111            let db = (bp[2] as f64 - ap[2] as f64) / 255.0;
1112            let da = (bp[3] as f64 - ap[3] as f64) / 255.0;
1113
1114            let dist_sq = (dr * dr + dg * dg + db * db + da * da) / 4.0;
1115
1116            if dist_sq > threshold_sq {
1117                diff_count += 1;
1118            }
1119        }
1120    }
1121
1122    Ok(ImageComparison {
1123        diff_count,
1124        diff_ratio: diff_count as f64 / total_pixels as f64,
1125    })
1126}
1127
1128/// Generate a diff image highlighting differences in red
1129fn generate_diff_image(
1130    baseline_bytes: &[u8],
1131    actual_bytes: &[u8],
1132    threshold: f64,
1133) -> Result<Vec<u8>> {
1134    use image::{GenericImageView, ImageBuffer, Rgba};
1135
1136    let baseline_img = image::load_from_memory(baseline_bytes).map_err(|e| {
1137        crate::error::Error::ProtocolError(format!("Failed to decode baseline image: {}", e))
1138    })?;
1139    let actual_img = image::load_from_memory(actual_bytes).map_err(|e| {
1140        crate::error::Error::ProtocolError(format!("Failed to decode actual image: {}", e))
1141    })?;
1142
1143    let (bw, bh) = baseline_img.dimensions();
1144    let (aw, ah) = actual_img.dimensions();
1145    let width = bw.max(aw);
1146    let height = bh.max(ah);
1147
1148    let threshold_sq = threshold * threshold;
1149
1150    let mut diff_img: ImageBuffer<Rgba<u8>, Vec<u8>> = ImageBuffer::new(width, height);
1151
1152    for y in 0..height {
1153        for x in 0..width {
1154            if x >= bw || y >= bh || x >= aw || y >= ah {
1155                // Out of bounds for one image — mark as diff
1156                diff_img.put_pixel(x, y, Rgba([255, 0, 0, 255]));
1157                continue;
1158            }
1159
1160            let bp = baseline_img.get_pixel(x, y);
1161            let ap = actual_img.get_pixel(x, y);
1162
1163            let dr = (bp[0] as f64 - ap[0] as f64) / 255.0;
1164            let dg = (bp[1] as f64 - ap[1] as f64) / 255.0;
1165            let db = (bp[2] as f64 - ap[2] as f64) / 255.0;
1166            let da = (bp[3] as f64 - ap[3] as f64) / 255.0;
1167
1168            let dist_sq = (dr * dr + dg * dg + db * db + da * da) / 4.0;
1169
1170            if dist_sq > threshold_sq {
1171                // Different — red highlight
1172                diff_img.put_pixel(x, y, Rgba([255, 0, 0, 255]));
1173            } else {
1174                // Same — semi-transparent grayscale of actual
1175                let gray = ((ap[0] as u16 + ap[1] as u16 + ap[2] as u16) / 3) as u8;
1176                diff_img.put_pixel(x, y, Rgba([gray, gray, gray, 100]));
1177            }
1178        }
1179    }
1180
1181    let mut output = std::io::Cursor::new(Vec::new());
1182    diff_img
1183        .write_to(&mut output, image::ImageFormat::Png)
1184        .map_err(|e| {
1185            crate::error::Error::ProtocolError(format!("Failed to encode diff image: {}", e))
1186        })?;
1187
1188    Ok(output.into_inner())
1189}
1190
1191#[cfg(test)]
1192mod tests {
1193    use super::*;
1194
1195    #[test]
1196    fn test_expectation_defaults() {
1197        // Verify default timeout and poll interval constants
1198        assert_eq!(DEFAULT_ASSERTION_TIMEOUT, Duration::from_secs(5));
1199        assert_eq!(DEFAULT_POLL_INTERVAL, Duration::from_millis(100));
1200    }
1201}
playwright_rs/assertions.rs

playwright_rs/
assertions.rs
