ScreenshotNeo

BlogHow-to

How to Fix WebdriverCSS When It Does Not Save Screenshots

WebdriverCSS can leave an empty screenshot folder when versions, paths, callbacks, or sessions are wrong. Use this diagnostic guide to find the cause.

By the ScreenshotNeo team30 September 20267 min read

How to Fix WebdriverCSS When It Does Not Save Screenshots

When WebdriverCSS does not save screenshots, check the resolved WebdriverCSS and WebdriverIO versions first. A historically documented failure with an empty ./webdrivercss directory was associated with WebdriverIO v3 incompatibility. Then verify that WebdriverCSS is initialized on the same client, that screenshotRoot is writable, and that the asynchronous capture finishes before the session ends.

The old compatibility warning is version-specific evidence, not a current compatibility matrix. Do not downgrade or upgrade until you have recorded the exact versions installed in your project.

1. Record the versions actually installed

Package ranges in package.json are not enough. Resolve the versions used by the test process:

Trace versions, client setup, callback completion, and the output path in that order.
Trace versions, client setup, callback completion, and the output path in that order.
npm ls webdrivercss webdriverio
npm explain webdrivercss
node --version

Also record the lockfile revision and the runner version used in CI. The reported WebdriverCSS issue came from a 2015-era setup, and the cited maintainer response said WebdriverCSS did not work with WebdriverIO v3 at that time. Treat that as historical evidence: your first task is to compare your installed versions with the versions your project was built to use.

2. Confirm the WebdriverCSS plugin is attached to the right client

The documented pattern initializes WebdriverCSS with require('webdrivercss').init(client, options), then calls client.webdrivercss(...). Initialization must happen on the exact WebdriverIO client that drives the browser.

const webdriverio = require('webdriverio');
const webdrivercss = require('webdrivercss');

const client = webdriverio.remote({
  desiredCapabilities: { browserName: 'chrome' }
});

webdrivercss.init(client, {
  screenshotRoot: './webdrivercss',
  failedComparisonsRoot: './webdrivercss/diff'
});

client
  .init()
  .url('https://example.com')
  .webdrivercss('example-home', [
    { name: 'desktop', width: 1280, height: 800 }
  ], function (error, result) {
    if (error) {
      console.error('WebdriverCSS capture failed:', error);
      return client.end();
    }

    console.log('WebdriverCSS result:', result);
    client.end();
  });

If your project creates more than one client, log the object used for init and the object used for webdrivercss. A plugin attached to one session cannot capture through another session.

3. Check where files are written

screenshotRoot controls screenshot output and defaults to ./webdrivercss. failedComparisonsRoot controls comparison diffs and defaults to ./webdrivercss/diff. Relative paths are resolved from the process execution directory, which may differ between a local shell, an npm script, and a CI runner.

const path = require('path');
console.log('execution directory:', process.cwd());
console.log('screenshot directory:', path.resolve('./webdrivercss'));

Use an absolute path while diagnosing:

const path = require('path');
const outputRoot = path.join(process.cwd(), 'artifacts', 'webdrivercss');

webdrivercss.init(client, {
  screenshotRoot: outputRoot,
  failedComparisonsRoot: path.join(outputRoot, 'diff')
});

Before running the test, create the parent directory and verify that the user running Node can write to it:

mkdir -p artifacts/webdrivercss
node -e "require('fs').writeFileSync('artifacts/webdrivercss/write-check.txt', 'ok')"
ls -la artifacts/webdrivercss

Do not assume that an empty directory means the browser failed. A wrong working directory, a container volume that is not mounted, or a CI artifact rule that excludes the folder can make a successful capture appear to be missing.

4. Verify the capture invocation and callback

WebdriverCSS documents the form client.webdrivercss('some_id', [{ options }], callback). Each capture option needs a name. Log both callback arguments and keep the session alive until the callback runs.

client.webdrivercss('checkout', [
  {
    name: 'wide',
    width: 1440,
    height: 900
  }
], function (error, result) {
  if (error) {
    console.error(error.stack || error);
    return;
  }

  console.dir(result, { depth: null });
});

Common lifecycle mistakes include calling client.end() immediately after starting the command, letting a Mocha/Jasmine test return before the callback, or swallowing the callback error. Put the browser shutdown inside the completion path.

5. A minimal diagnostic script

Run this outside your full test suite. It isolates version, path, navigation, capture, and shutdown problems:

const fs = require('fs');
const path = require('path');
const webdriverio = require('webdriverio');
const webdrivercss = require('webdrivercss');

const root = path.resolve('artifacts/webdrivercss');
fs.mkdirSync(root, { recursive: true });
fs.accessSync(root, fs.constants.W_OK);

const client = webdriverio.remote({
  desiredCapabilities: { browserName: 'chrome' }
});

webdrivercss.init(client, {
  screenshotRoot: root,
  failedComparisonsRoot: path.join(root, 'diff')
});

client
  .init()
  .url('https://example.com')
  .getTitle(function (titleError, title) {
    if (titleError) throw titleError;
    console.log('page title:', title);

    client.webdrivercss('diagnostic', [
      { name: 'desktop', width: 1280, height: 800 }
    ], function (captureError, result) {
      try {
        if (captureError) {
          console.error(captureError.stack || captureError);
          process.exitCode = 1;
          return;
        }
        console.dir(result, { depth: null });
        console.log('files:', fs.readdirSync(root));
      } finally {
        client.end();
      }
    });
  });

6. If you are on current WebdriverIO, compare the native API

Current WebdriverIO documentation provides an element screenshot API named saveScreenshot. It is a different route from the WebdriverCSS plugin and does not establish WebdriverCSS compatibility. The filename should end in .png, and the path is relative to the execution directory.

describe('element screenshot', () => {
  it('saves a PNG', async () => {
    await browser.url('https://example.com');
    const heading = await $('h1');
    await heading.saveScreenshot('./artifacts/example-heading.png');
  });
});

Use this route when you need a current WebdriverIO element image and do not need WebdriverCSS comparison behavior. If your project depends on WebdriverCSS baselines, compare the generated file layout and diff workflow before migrating.

7. Troubleshooting checklist

Symptom Likely cause Fix
./webdrivercss stays empty WebdriverIO v3 incompatibility in the historical stack Record resolved versions and match them against the versions supported by your project; do not assume a downgrade is correct.
No files, no visible error Callback error is ignored or the process exits early Log the error and result, keep the session open, and shut it down only after the callback.
Files appear in an unexpected directory Relative path is based on a different process.cwd() Print the working directory and use an absolute screenshotRoot.
Capture fails before writing WebdriverCSS was initialized on another client Call init and webdrivercss on the same client object.
Diff folder is empty No comparison was produced or the diff root is different Check failedComparisonsRoot and inspect the callback result.
Works locally but times out in CI Runner, connection, session timing, or environment differences Compare local and CI logs, browser/session lifetime, network access, and working directories. A historical TeamCity report shows this class of difference is possible, not that it is always the cause.
Native WebdriverIO call rejects the path Filename does not use the expected PNG suffix Pass a path ending in .png to saveScreenshot.

8. CI and runner checks

  1. Print Node, WebdriverIO, WebdriverCSS, browser, and driver versions.
  2. Print process.cwd() and the resolved screenshot root.
  3. Save the complete callback error and result as CI artifacts.
  4. Confirm the browser session remains open until capture completion.
  5. Check that the CI user can write to the output volume.
  6. Run the same diagnostic URL locally and in CI.
  7. Compare navigation timing, proxy settings, credentials, and network access.

9. Choosing a path forward

Path Use it when Trade-off
Keep the legacy WebdriverCSS project Your dependency set is pinned and the existing visual-regression workflow is required. Least code change, but the supplied evidence does not establish present-day maintenance or compatibility.
Use WebdriverIO saveScreenshot You need a current element PNG and can manage comparisons elsewhere. Simple native API, but it is not the WebdriverCSS plugin workflow.
Use a screenshot API You want capture without maintaining browser setup, drivers, and session lifecycle. Requires an API key and a request-based workflow.
A request based capture avoids local driver and filesystem setup.
A request based capture avoids local driver and filesystem setup.

Or skip the browser setup

ScreenshotNeo takes a screenshot with one GET request and supports PNG, JPEG, WebP, and PDF output. Its API documentation is at screenshotneo.com/docs.

cURL

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

Python

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)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and whether the request was billed. An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and try the request without adding a card.

Performance, reliability, and cost notes

  • Keep a browser session alive only for the capture work; premature shutdown is both a correctness and a speed problem.
  • Use a focused diagnostic URL before testing a large suite so navigation, driver, and filesystem failures are separated.
  • In CI, persist screenshot and log directories as artifacts so an empty workspace can be distinguished from a failed capture.
  • For API captures, caching can avoid repeated work when an unchanged page is acceptable; ScreenshotNeo lets you choose a cache TTL.
  • ScreenshotNeo supports custom headers, cookies, user agents, authorization, timezone, geolocation, blocking rules, waits, selectors, device presets, retina scale, and asynchronous jobs when a single synchronous browser test is not the right fit.

FAQ

Should I immediately downgrade WebdriverIO?

No. First record the resolved versions and compare them with the historical compatibility warning. The available evidence does not define a safe downgrade target for every project.

Does an empty screenshot folder prove the browser did not navigate?

No. It can also indicate a wrong working directory, an unwritable destination, an ignored callback error, or a session that ended before the asynchronous command completed.

Is saveScreenshot a drop-in replacement for WebdriverCSS?

No. It is WebdriverIO’s native element screenshot API. It can save a PNG, but it does not by itself reproduce WebdriverCSS comparison and baseline behavior.

What details should I include when asking for help?

Include exact resolved package versions, Node and browser versions, the initialization code, the capture call, callback output, process.cwd(), resolved screenshot paths, and whether the failure occurs locally, in CI, or both.