playwright_rs/protocol/

coverage.rs

// Coverage — Chromium-only code coverage collection
//
// See: https://playwright.dev/docs/api/class-coverage

use crate::error::Result;
use crate::protocol::page::Page;

/// Options for `Coverage::start_js_coverage`.
///
/// See: <https://playwright.dev/docs/api/class-coverage#coverage-start-js-coverage>
#[derive(Debug, Default, Clone)]
#[non_exhaustive]
pub struct StartJSCoverageOptions {
    /// Whether to reset coverage on every navigation.
    ///
    /// Defaults to `true`.
    pub reset_on_navigation: Option<bool>,

    /// Whether to report anonymous scripts generated by the page.
    ///
    /// Defaults to `false`.
    pub report_anonymous_scripts: Option<bool>,
}

impl StartJSCoverageOptions {
    /// Whether to reset coverage on every navigation. Defaults to `true`.
    pub fn reset_on_navigation(mut self, reset_on_navigation: bool) -> Self {
        self.reset_on_navigation = Some(reset_on_navigation);
        self
    }

    /// Whether to report anonymous scripts generated by the page. Defaults
    /// to `false`.
    pub fn report_anonymous_scripts(mut self, report_anonymous_scripts: bool) -> Self {
        self.report_anonymous_scripts = Some(report_anonymous_scripts);
        self
    }
}

/// Options for `Coverage::start_css_coverage`.
///
/// See: <https://playwright.dev/docs/api/class-coverage#coverage-start-css-coverage>
#[derive(Debug, Default, Clone)]
#[non_exhaustive]
pub struct StartCSSCoverageOptions {
    /// Whether to reset coverage on every navigation.
    ///
    /// Defaults to `true`.
    pub reset_on_navigation: Option<bool>,
}

impl StartCSSCoverageOptions {
    /// Whether to reset coverage on every navigation. Defaults to `true`.
    pub fn reset_on_navigation(mut self, reset_on_navigation: bool) -> Self {
        self.reset_on_navigation = Some(reset_on_navigation);
        self
    }
}

/// A byte-offset range within a CSS stylesheet.
///
/// Used in [`CSSCoverageEntry`].
#[derive(Debug, Clone, serde::Deserialize)]
#[non_exhaustive]
pub struct CoverageRange {
    /// Start byte offset (inclusive).
    pub start: usize,
    /// End byte offset (exclusive).
    pub end: usize,
}

/// A byte-offset range with hit count within a JavaScript function.
///
/// Used in [`JSFunctionCoverage`].
#[derive(Debug, Clone, serde::Deserialize)]
#[non_exhaustive]
pub struct JSCoverageRange {
    /// Start byte offset (inclusive).
    #[serde(rename = "startOffset")]
    pub start_offset: usize,
    /// End byte offset (exclusive).
    #[serde(rename = "endOffset")]
    pub end_offset: usize,
    /// Number of times this range was executed.
    pub count: i64,
}

/// Per-function coverage data within a [`JSCoverageEntry`].
#[derive(Debug, Clone, serde::Deserialize)]
#[non_exhaustive]
pub struct JSFunctionCoverage {
    /// The function name (empty string for anonymous functions).
    #[serde(rename = "functionName")]
    pub function_name: String,
    /// Whether this is block-level coverage (true) or function-level (false).
    #[serde(rename = "isBlockCoverage")]
    pub is_block_coverage: bool,
    /// Covered byte-offset ranges within this function.
    pub ranges: Vec<JSCoverageRange>,
}

/// A JavaScript coverage entry returned by `Coverage::stop_js_coverage`.
///
/// See: <https://playwright.dev/docs/api/class-coverage#coverage-stop-js-coverage>
#[derive(Debug, Clone, serde::Deserialize)]
#[non_exhaustive]
pub struct JSCoverageEntry {
    /// The URL of the script.
    pub url: String,
    /// The V8 script ID.
    #[serde(rename = "scriptId")]
    pub script_id: String,
    /// The script source text.
    pub source: Option<String>,
    /// Per-function coverage data.
    pub functions: Vec<JSFunctionCoverage>,
}

/// A CSS coverage entry returned by `Coverage::stop_css_coverage`.
///
/// See: <https://playwright.dev/docs/api/class-coverage#coverage-stop-css-coverage>
#[derive(Debug, Clone, serde::Deserialize)]
#[non_exhaustive]
pub struct CSSCoverageEntry {
    /// The URL of the stylesheet.
    pub url: String,
    /// The stylesheet source text.
    pub text: Option<String>,
    /// Byte-offset ranges of used CSS rules.
    pub ranges: Vec<CoverageRange>,
}

/// Provides JavaScript and CSS code coverage collection (Chromium only).
///
/// Access via [`Page::coverage`].
///
/// Coverage collection is only supported in Chromium. Calling these methods on
/// Firefox or WebKit will return an error.
///
/// See: <https://playwright.dev/docs/api/class-coverage>
#[derive(Clone)]
pub struct Coverage {
    page: Page,
}

impl Coverage {
    pub(crate) fn new(page: Page) -> Self {
        Self { page }
    }

    /// Starts collecting JavaScript coverage.
    ///
    /// Must be called before navigating to the page(s) you want to measure.
    ///
    /// # Errors
    ///
    /// Returns error if coverage is already started, if the browser is not
    /// Chromium, or if the RPC call fails.
    ///
    /// See: <https://playwright.dev/docs/api/class-coverage#coverage-start-js-coverage>
    pub async fn start_js_coverage(
        &self,
        options: impl Into<Option<StartJSCoverageOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.page.coverage_start_js(options).await
    }

    /// Stops JavaScript coverage collection and returns the entries.
    ///
    /// # Errors
    ///
    /// Returns error if coverage was not started or if the RPC call fails.
    ///
    /// See: <https://playwright.dev/docs/api/class-coverage#coverage-stop-js-coverage>
    pub async fn stop_js_coverage(&self) -> Result<Vec<JSCoverageEntry>> {
        self.page.coverage_stop_js().await
    }

    /// Starts collecting CSS coverage.
    ///
    /// # Errors
    ///
    /// Returns error if coverage is already started, if the browser is not
    /// Chromium, or if the RPC call fails.
    ///
    /// See: <https://playwright.dev/docs/api/class-coverage#coverage-start-css-coverage>
    pub async fn start_css_coverage(
        &self,
        options: impl Into<Option<StartCSSCoverageOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.page.coverage_start_css(options).await
    }

    /// Stops CSS coverage collection and returns the entries.
    ///
    /// # Errors
    ///
    /// Returns error if coverage was not started or if the RPC call fails.
    ///
    /// See: <https://playwright.dev/docs/api/class-coverage#coverage-stop-css-coverage>
    pub async fn stop_css_coverage(&self) -> Result<Vec<CSSCoverageEntry>> {
        self.page.coverage_stop_css().await
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn js_coverage_setters_write_their_own_fields() {
        let opts = StartJSCoverageOptions::default()
            .reset_on_navigation(false)
            .report_anonymous_scripts(true);
        assert_eq!(opts.reset_on_navigation, Some(false));
        assert_eq!(opts.report_anonymous_scripts, Some(true));
    }

    #[test]
    fn css_coverage_setter_writes_the_field() {
        let opts = StartCSSCoverageOptions::default().reset_on_navigation(false);
        assert_eq!(opts.reset_on_navigation, Some(false));
    }
}