How to Capture Screenshots with Selenide

Yes—Selenide captures a screenshot automatically when a test fails. In the documented default setup, failure screenshots go in build/reports/tests. To capture deliberately at a particular point, call Selenide.screenshot("name"); to use the image in code, request bytes, Base64, or a file with screenshot(OutputType...). The examples below follow the current Selenide Javadocs, identified as version 7.18.2 in the supplied research. See the official screenshots guide and Selenide API.

1. What happens when a Selenide test fails?

For a typical failed Selenide condition, automatic screenshot capture is enabled by default. Selenide writes the image as part of its failure artifacts. The screenshots guide documents build/reports/tests as the default folder. This is a filesystem location; whether the file is uploaded or attached to a CI report depends on your build and CI configuration.

For example, if a condition such as $("h1").shouldHave(text("Ready")) fails, first inspect the test report directory for the screenshot and page source. The image can show the rendered page at failure time, while the source artifact can help explain the DOM state. They are separate artifacts and can be controlled separately.

2. Configure the screenshot folder and automatic capture

Set the reports folder once during test setup, before tests run. The Java property and the JVM system property are equivalent configuration routes:

import com.codeborne.selenide.Configuration;

public class SelenideTestConfig {
    static {
        Configuration.reportsFolder = "test-result/reports";
    }
}

Or pass the property to the test JVM:

./gradlew test -Dselenide.reportsFolder=test-result/reports

To turn off automatic screenshots on failure, set Configuration.screenshots to false or use the property:

Configuration.screenshots = false;
// Alternatively: ./gradlew test -Dselenide.screenshots=false

The configuration setting governs automatic failure screenshots. It does not prevent an explicit call to screenshot("name") from creating its named PNG. See the Configuration Javadoc for the available settings and defaults.

3. Take a named screenshot in Java

Use the static Selenide method when you want a deliberate capture and a report artifact:

import static com.codeborne.selenide.Selenide.open;
import static com.codeborne.selenide.Selenide.screenshot;
import static com.codeborne.selenide.Selenide.$;
import static com.codeborne.selenide.Condition.text;

public class CheckoutTest {
    @org.junit.jupiter.api.Test
    void captureCheckoutState() {
        open("https://example.com/checkout");
        $("h1").shouldHave(text("Checkout"));

        String pngFileName = screenshot("checkout-ready");
        System.out.println("Screenshot: " + pngFileName);
    }
}

The name is a base filename without an extension; Selenide creates a PNG such as checkout-ready.png in the reports area. Keep names unique when a test can capture multiple states, and prefer stable identifiers over timestamps if you want predictable artifact paths.

For a quick capture in a test, the essential call is simply:

String fileName = screenshot("before-submit");

The named call also may write page source depending on page-source configuration. The screenshot is a PNG; page source is a separate HTML or, with the relevant Chromium option, MHTML artifact.

4. Capture bytes, Base64, or a temporary file

Use the output-type overload when another part of your test needs the image representation rather than a named artifact. The API supports OutputType.BYTES, OutputType.BASE64, and OutputType.FILE.

import com.codeborne.selenide.Selenide;
import org.openqa.selenium.OutputType;

byte[] png = Selenide.screenshot(OutputType.BYTES);
String base64Png = Selenide.screenshot(OutputType.BASE64);
java.io.File temporaryPng = Selenide.screenshot(OutputType.FILE);

These calls request an image from the active WebDriver. The API documents that the result may be null if the driver does not support screenshots. Check for null before using it in a generic driver setup. A returned temporary file is not guaranteed to remain available after the test completes, so copy it to a durable location while the test is running if it must survive cleanup.

java.io.File temp = Selenide.screenshot(OutputType.FILE);
if (temp != null) {
    java.nio.file.Path destination = java.nio.file.Path.of("build", "artifacts", "current.png");
    java.nio.file.Files.createDirectories(destination.getParent());
    java.nio.file.Files.copy(temp.toPath(), destination,
            java.nio.file.StandardCopyOption.REPLACE_EXISTING);
}

Use the named screenshot call for a stable report artifact. Use bytes or Base64 when the next step consumes the image in memory. Use the file output type only when you manage its lifetime explicitly.

5. Capture an element or an iframe element

Selenide also documents screenshot methods for elements and iframe elements. These are useful when the relevant evidence is a particular component, such as a chart or modal, rather than the current page. The element-oriented API is documented in Screenshots and the Selenide API.

import static com.codeborne.selenide.Selenide.$;
import org.openqa.selenium.OutputType;

byte[] componentPng = $(".invoice-summary").screenshot().getBytes();

Check the element screenshot method available in the Selenide version you use; element APIs and WebDriver support can affect the exact call and result. The cited documentation supports element and iframe element methods, but do not assume those methods perform full-page scrolling capture. For a page-level screenshot, use the page screenshot API.

6. Keep the HTML or include page resources

The PNG and page source are separate outputs. Configuration.savePageSource controls source capture and is documented with a default of true; the ordinary source artifact is HTML. To request resources bundled with the source in Chromium, use Configuration.savePageSourceWithResources:

Configuration.savePageSource = true;
Configuration.savePageSourceWithResources = true;

The current Configuration Javadoc lists savePageSourceWithResources as false by default. In Selenide 7.18.0, the release notes describe MHTML capture through Chrome DevTools Protocol’s Page.captureSnapshot. If Chromium/CDP capture is unavailable or fails, Selenide falls back to plain HTML. Treat this as a versioned Chromium behavior, not a guarantee across all browsers or drivers. The 7.18.0 release notes include one example’s file sizes; those are individual examples, not representative benchmarks.

Page source can make failures easier to diagnose when rendered appearance alone is ambiguous. It also adds artifacts, so choose whether it belongs in your routine CI output based on how your team investigates failures and stores test results.

7. Capture on success or on failures outside Selenide conditions

Automatic Selenide failure capture is the straightforward default for failures detected through Selenide checks. If you need screenshots for successful tests or for assertion failures outside Selenide conditions, the screenshots guide documents test-runner integrations: ScreenShooterExtension for JUnit 5 and a listener for TestNG. It also shows a Kotlin extension example.

Use the extension or listener matching your actual runner and dependency versions, and follow the setup in the Selenide screenshots guide. The integration controls when capture happens at the test-runner level; it does not change the distinction between the PNG and optional page-source artifacts. Avoid assuming that a runner hook automatically publishes files to a remote CI report: artifact collection and upload still depend on your build pipeline.

8. Or skip the browser setup

If you need a screenshot of a public web page rather than evidence from the browser session controlled by your test, ScreenshotNeo provides a one-request screenshot API and an MCP server. It does not replace Selenide’s ability to capture the exact state of an in-progress test. The request below captures a URL directly; see the ScreenshotNeo API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Other plans are Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000), and Business ($249 for 1,000,000); annual billing gives two months free, and every feature is available on every plan.

Sign up for 1,000 free screenshots a month with no card.

9. Troubleshooting common screenshot issues

Symptom	Likely cause	What to do
No failure screenshot appears	Automatic screenshots were disabled, the failure did not pass through the expected Selenide path, or the artifact folder is elsewhere.	Check Configuration.screenshots and selenide.screenshots; inspect the configured reportsFolder. For runner-wide coverage, use the documented JUnit 5 extension or TestNG listener.
Screenshot exists locally but not in CI report	The CI job or build has not collected or uploaded that directory.	Configure artifact collection for the reports folder in the build/CI system. Selenide’s capture does not itself guarantee report attachment.
Named call creates a PNG although screenshots are disabled	This is expected: the flag controls automatic failure screenshots.	Remove or conditionally execute the explicit screenshot("name") call if you do not want that capture.
Returned file disappears after the test	OutputType.FILE returns a temporary file whose persistence is not guaranteed.	Copy it to a durable path during the test, or use the named screenshot API for a report artifact.
Screenshot result is null	The active WebDriver may not support taking screenshots.	Check driver capabilities and null-check the result before consuming it. The API documents null as a possible result.
Only HTML is saved when resources were expected	MHTML capture requires the supported Chromium/CDP path and can fall back when capture is unavailable or unsuccessful.	Confirm the browser is Chromium and the configured Selenide release supports the behavior. Keep HTML fallback in mind when diagnosing the artifact.
Capture represents an unexpected page state	The screenshot ran before navigation or asynchronous UI changes completed.	Wait for a meaningful Selenide condition before the deliberate capture, such as an element being visible or containing expected text.

10. Performance, reliability, and storage considerations

A screenshot adds image output to a test run, and page-source capture can add another artifact. The supplied official sources do not establish a general timing or storage benchmark, so estimate impact using your own pages, browser setup, and CI retention policy. The Selenide 7.18.0 release post’s individual sample sizes should not be used as a sizing promise.

For reliable evidence, capture after the page reaches the state you want to inspect, use descriptive names for deliberate captures, and preserve the configured report directory as a CI artifact. If a file must outlive the test process, copy it to managed storage before cleanup. If failure evidence needs broader test-runner coverage, configure the runner integration rather than relying only on condition failures. On remote browsers, artifact retrieval and persistence depend on the execution and CI setup; the Selenide FAQ lists Selenoid, Moon, BrowserStack, LambdaTest, TestMu AI, TestContainers, and other cloud contexts, but does not imply any particular artifact workflow.

11. Frequently asked questions

Can I save a screenshot with a different image format?

The documented Selenide screenshot APIs described here produce PNG screenshots. The supplied sources do not document a setting for choosing JPEG or WebP output.

Can Selenide take a screenshot of a full page by scrolling?

The cited sources document page screenshots and element screenshots, but do not establish full-page scrolling capture. Do not assume a page screenshot includes content beyond the browser’s captured viewport.

Can I send the image to another service?

Request bytes or Base64 when another API or your own code needs the image content. For a temporary file, copy it to a durable location before test cleanup.

Does saving page source create a screenshot?

No. Page source is a separate HTML or MHTML artifact. Use the screenshot setting or explicit screenshot method for the PNG.

12. Practical checklist

1. Confirm automatic screenshots are enabled if you want evidence on failed Selenide checks.
2. Set reportsFolder to a path your test and CI setup can preserve.
3. Use screenshot("descriptive-name") for a deliberate PNG artifact.
4. Use BYTES, BASE64, or FILE only when code needs that representation; persist temporary files explicitly.
5. Decide separately whether HTML source or Chromium MHTML belongs with the image.
6. Add the documented JUnit 5 or TestNG integration when successful tests or non-Selenide assertion failures also need capture.