Test Plugins

A test plugin runs code around a test: when it starts, when it fails (with the browser still open, so it can take evidence), and when it finishes. The ones that ship with the crate save a screenshot and the page source on failure and write a report. They are the counterpart of Python SeleniumBase’s pytest plugins.

The hooks of a test plugin

Attaching plugins to a test#

Build a Plugins set and run the test through it. It works like run_browser_test, and returns the same result:

use seleniumbase_rs::plugins::observer::Plugins;use seleniumbase_rs::plugins::page_source::PageSourceOnFailurePlugin;use seleniumbase_rs::plugins::reports::ReportPlugin;use seleniumbase_rs::plugins::screen_shots::ScreenshotOnFailurePlugin;use seleniumbase_rs::BrowserConfig;# async fn demo() -> Result<(), seleniumbase_rs::SeleniumBaseError> {let mut plugins = Plugins::new()    .with(ScreenshotOnFailurePlugin::new("latest_logs"))    .with(PageSourceOnFailurePlugin::new("latest_logs"))    .with(ReportPlugin::json("latest_logs/report.json"));plugins    .run_browser_test("login_works", BrowserConfig::default(), async |sb| {        sb.open("https://example.com").await?;        sb.assert_title("Example Domain").await    })    .await?;# Ok(())# }

Reuse one Plugins value for every test in a run. A ReportPlugin keeps the results it has seen and rewrites its file after each test, so the report is valid even if the run stops part-way.

The bundled plugins#

Details worth knowing:

• Files are never overwritten: a second failure of the same test in the same second gets a numbered name.
• A test name is turned into letters, digits, - and _ before it is used in a file name, so a test called ../../etc/passwd cannot write outside the directory you chose.
• If the browser cannot take the screenshot (it has crashed, say), no file is written. An earlier version wrote a text note into a .png file; a file that only pretends to be a screenshot is worse than none.

With the Pure CDP engine#

Evidence comes from anything that implements PageEvidence. It is implemented for BaseCase and for sb_cdp::Page, so the same plugins work with either.

use seleniumbase_rs::plugins::observer::Plugins;use seleniumbase_rs::plugins::screen_shots::ScreenshotOnFailurePlugin;use seleniumbase_rs::sb_cdp::LaunchOptions;# async fn demo() -> Result<(), seleniumbase_rs::SeleniumBaseError> {let mut plugins = Plugins::new().with(ScreenshotOnFailurePlugin::new("latest_logs"));plugins    .run_cdp_test("checkout", LaunchOptions::default(), async |page| {        page.goto("https://example.com").await?;        page.locator("#buy").click().await    })    .await?;# Ok(())# }

use seleniumbase_rs::plugins::observer::Plugins;use seleniumbase_rs::plugins::screen_shots::ScreenshotOnFailurePlugin;use seleniumbase_rs::sb_cdp::{Browser, LaunchOptions};# async fn demo() -> Result<(), seleniumbase_rs::SeleniumBaseError> {let browser = Browser::launch(LaunchOptions::default()).await?;let page = browser.default_page().await?;let mut plugins = Plugins::new().with(ScreenshotOnFailurePlugin::new("latest_logs"));plugins.started("checkout").await;let outcome = async {    page.goto("https://example.com").await?;    page.locator("#buy").click().await}.await;if let Err(error) = &outcome {    plugins.failed("checkout", error, &page).await; // takes the screenshot now}plugins.finished("checkout", std::time::Duration::ZERO, &outcome).await;# Ok(())# }

Writing your own#

Implement TestPlugin. Every hook is optional and returns a Result:

use async_trait::async_trait;use seleniumbase_rs::plugins::observer::{PageEvidence, TestPlugin};use seleniumbase_rs::SeleniumBaseError;struct SlackOnFailure;#[async_trait]impl TestPlugin for SlackOnFailure {    async fn test_failed(        &mut self,        test: &str,        error: &SeleniumBaseError,        page: &dyn PageEvidence,    ) -> Result<(), SeleniumBaseError> {        let png = page.screenshot_png().await?;        // ... post `test`, `error` and `png` somewhere ...        # let _ = (test, error, png);        Ok(())    }}

When a plugin fails#

Uploading what a plugin saved#

S3LoggingPlugin, AzureLoggingPlugin and GcpLoggingPlugin are uploaders, not hooks: call their upload_file after a test on the files the failure plugins wrote. See Cloud Integrations.

Migrating from the old plugin API#

What has and has not been verified#