# testplane: a mocha and WebdriverIO runner built for visual diffing

> Testplane, the renamed Hermione, is a browser test runner for JavaScript projects that pairs a familiar mocha and WebdriverIO foundation with a first class visual regression workflow, a GUI, and sharding for large suites. It is MIT licensed, and the visual assertion workflow is the part most runners do not give you.

**gemini-testing/testplane** — Testplane (ex-hermione) browser test runner based on mocha and wdio

- Repository: https://github.com/gemini-testing/testplane
- Website: https://testplane.io
- Stars: 832 · Forks: 79
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/gemini-testing-testplane

## A runner with visual testing at its centre

Testplane, previously Hermione, describes itself as a battle-hardened framework for testing web apps at any scale, any browser and any platform, and the repository description calls it a browser test runner based on mocha and wdio.

That foundation is the first thing to understand. It is not a new testing paradigm. The test bodies are mocha suites, the browser automation goes through WebdriverIO, and the expectations use a familiar style. If your team already writes browser tests in that idiom, the migration cost is a configuration change and a rename rather than a rewrite.

What Testplane adds is a set of things the underlying stack does not give you, and the first of them is visual testing. The README describes it as visual testing redefined: capture anything from specific details to whole pages, manage diffs with a streamlined UI, explore a variety of diff modes, and let Testplane handle flakiness. The visual regression workflow is the reason the project exists as more than a mocha and wdio wrapper, and it is built around a dedicated command rather than a plugin bolted on afterwards.

The other additions are operational. Sharding, parallel test execution and isolated browser contexts, so a suite of thousands can run on a remote browser grid or locally at speed. An installation wizard, TypeScript support, live test editing with instant feedback, an advanced HTML reporter, and auto-wait and retries to handle the flakiness that browser tests are notorious for.

The target audience is a team with a real web product and a real test suite, rather than someone learning to write their first browser test. The topic list on the repository is a good summary of scope, covering e2e-testing, component-testing, integration-testing, screenshot-testing, chrome, firefox and webkit, and the keywords include testing-tools, testplane and screenshot-testing.

## The visual assertion is a command, not a plugin

The getting started walkthrough is short and it shows the shape of the whole thing, so it is worth reading closely.

The first test is an ordinary one. You open a page, find an element, and assert on its text:

```typescript
describe("test", () => {
    it("example", async ({browser}) => {
        await browser.url("https://example.com/");

        const description = await browser.$("p");

        await expect(description).toHaveTextContaining("for use in illustrative examples in documents");
    });
});
```

The browser is injected into the test as a fixture, and element lookup uses the familiar dollar sign form, so the test reads like any other wdio based suite.

Then the text assertion is replaced with a visual one, and this is the line that defines the product:

```typescript
await description.assertView("description"); // "description" is just a name of the assertion
```

The comment is doing real work. The string is the name of the assertion, not a selector or a path. That name becomes the identity of the reference image, so the same name always compares against the same snapshot, and the name is what appears in the diff review interface when the assertion fails.

The flow the README describes makes the design clear. You run the test and it fails, because there is no reference image for the heading yet. You accept the diff and re-run, and it passes. That first-failure-then-accept loop is the standard snapshot workflow, and Testplane's contribution is the diff management UI, the range of diff modes, and the flakiness handling around it.

The scope is wide. You can capture anything from specific details to whole pages, which means the same mechanism serves a single component, a widget, and a full page screenshot, and the granularity is a per-assertion decision rather than a project-wide one.

## Getting set up with the CLI wizard

The installation path is a CLI wizard that also generates the configuration, which removes the usual first hour of setting up a wdio project.

The command is:

```shell
npm init testplane@latest new-testplane-project
```

If you would rather install manually, the README notes you can run `npm i -D testplane` instead, and points to the docs for details.

The wizard generates a test file at testplane-tests/example.testplane.ts, and the filename extension is worth noting because it is how the framework distinguishes its own test files from the wdio spec files, so a project can hold both. The `-- --verbose` argument launches the tool in extra-questions mode, where you can pick a custom package manager or install extra plugins during setup rather than afterwards.

There is also a GUI:

```shell
npx testplane gui
```

For a framework whose selling point includes visual diff review, having a graphical interface rather than only a terminal reporter is a deliberate choice. The GUI is where the diff review happens, and the HTML reporter is the artifact you attach to a pull request or a release ticket.

The docs list shows how much surface there is. There are pages for the features overview, quick start, dealing with browsers, writing tests, a browser commands reference, the config reference, TypeScript usage, the CLI, events, the programmatic API, component testing marked experimental, and debugging. The programmatic API and the events page matter if you intend to run Testplane from your own scripts rather than from the command line, and the events page is what you need if you want to hook into the run lifecycle.

The docs live on testplane.io, and the README notes that the most current information, guides and changelogs are on the website, with pull requests going to a separate testplane-docs repository.

## Running the same tests in Node and in the browser

The environment question is where Testplane differs most from a plain wdio setup, and the answer is that the environment is a per-project decision rather than a fixed assumption.

The README states that with Testplane you can run tests not only in a Node.js environment but also in the browser, which means you can run end to end and integration tests in Node.js and component or unit tests in the browser. The component testing page is marked experimental in the docs index, which is worth noting for anyone planning to base a unit testing strategy on it.

Running unit tests in a real browser rather than in a jsdom-like environment is the meaningful part of that. A DOM emulation in Node gives you a document but not layout, not paint, not real font metrics, and no screenshots. A test that asserts on rendered geometry is testing something different in the two environments, and a test that takes a screenshot only means anything in the browser.

The build scripts in the package.json show the work behind that. There is a separate browser bundle and a Node bundle, built with esbuild for the Node side targeting ES2021 and platform node, and a browser bundle built by a script under src/browser/client-scripts that also builds a screen-shooter and a browser-utils bundle. The published files array contains only build and typings, and the exports map has a root entry and an unstable entry, both offering require and import conditions.

The screen-shooter bundle is the visual testing machinery, and it is built as a separate browser bundle precisely because the screenshotting code has to run in the browser, inside the page being captured, not in the Node process that drives it.

The browsers themselves are managed by the framework, with a script to resolve Ubuntu package dependencies for the browser installer, and a development script that launches a Chromium container through Docker for local work. The docs have a dedicated page on dealing with browsers.

## Scale: sharding, parallelism and isolated contexts

The scalability story is three mechanisms, and they address three different bottlenecks.

Sharding splits the suite across machines so that several workers can run disjoint slices of the tests at the same time. That is the answer to a suite that takes longer than your CI window, and it requires a grid, because each shard needs a browser to drive.

Parallel test execution within a worker is a different thing, and it is where isolated browser contexts earn their keep. A test that leaves state behind, a cookie or a local storage entry, will corrupt the next test that runs in the same browser profile. Isolating each test in its own context removes that class of interference, which is one of the main reasons browser suites are flaky.

The grid is the third piece. The README describes running thousands of tests on a remote browser grid, or ultra-fast local execution, and it is explicit that the point is not being tied to a couple of latest Chrome builds. Testing on real devices and a broad range of automation protocols is the answer to the other common complaint about browser testing, that the environment you test in is not the environment your users are on.

The general position the project takes is that the test runner should not force a single opinionated architecture. It ships the pieces, and the plugin system, custom reporters, custom commands and custom execution logic are the extension points.

The plugin ecosystem is described as dozens of open source plugins on GitHub. That is a meaningful signal about the health of the project, and it is also a dependency you inherit, since a plugin pinned to a major version will constrain your upgrade path. The browser commands reference in the docs is where you find out what the framework offers out of the box, and it is also the extension surface for a custom command.

## The Hermione rename, and what it means for you

The project was formerly known as Hermione, and the reason for the change is stated: eventually some copyright and trademark issues surfaced, leading to the decision to rebrand, and after some discussion they settled on Testplane as the official new title.

The detail that matters for anyone running it in production is the version scheme. They considered the change as merely a rebranding and proceeded with the existing version count instead of starting anew, so Testplane v8.x is a drop-in replacement for Hermione v8.x.

That is a promise about compatibility, and it is a promise you should test rather than assume. A drop-in replacement means the configuration keys, the command names and the plugin interface are the same, but it does not mean every plugin on npm has been updated, and a plugin that depends on internal Hermione paths may break even though the public API did not change.

The release history in the repository is consistent with a project running two lines in parallel. There is a v9.3.3 from 2026-10-15 and a v9.3.2 from 2026-10-07, and there is also a v8.47.7 from the same day as v9.3.3. The 8.x line is still receiving patch releases alongside the 9.x line, which is what a rename with a compatibility promise looks like in practice, and it also means you can stay on 8.x for a while and still get fixes.

The migration guide is in the docs, under migrations, how to upgrade hermione to testplane. The last push was on 2026-10-21, the repository is not archived, and the releases listed are recent, so the project is being actively worked on.

## Where the framework is the wrong choice

There is a clear case against Testplane, and it is not about quality.

If your team has no visual regression requirement, most of the value proposition is unused. The wizard, the GUI, the diff modes, the flakiness tooling around screenshots, that is the bulk of the difference from a plain WebdriverIO plus Mocha setup, and a plain setup is less to learn and less to maintain. The visual assertion is the reason to be here, and if you are not doing visual assertions, you are carrying the weight for nothing.

The second limit is the rename's residual risk. Because the project changed identity mid-life, the plugin ecosystem has to have been reconciled, and a plugin that was never updated still exists in package registries. The compatibility promise covers the core, and the plugins are the part you have to check individually.

The third limit is browser support in practice. The framework supports Chrome, Firefox and Webkit, and it works with a remote grid, but the grid is a piece of infrastructure you have to run, and the browsers in that grid have to be a version combination the framework supports. The README's own framing of not being tied to a couple of latest Chrome builds is a selling point, and it also means the set of supported versions moves.

The alternative approaches differ in what they cost. Plain WebdriverIO with Mocha is the minimal path and gives you the browser automation without the visual layer. A dedicated visual regression service, where the diff review and reference storage live in a hosted product, gives you a better review experience and takes infrastructure off your plate. Playwright's own test runner is a different structure entirely, with a built-in expectation API and its own trace and network tooling, and it is a sensible comparison point because it also aims at the same problem of a browser test runner that developers do not have to fight.

The last thing to check before committing is scale. The sharding and grid machinery is designed for a suite of thousands of tests, and if you have forty tests the operational surface is larger than the value it delivers. For a small suite, the wizard and the GUI are still pleasant, but the rest is overhead.

## Conclusion

Adopt testplane if your team already runs browser tests through a mocha style runner and the missing piece is visual regression review rather than test authoring. Do not adopt it for a greenfield suite with no visual requirements, since the visual tooling is the bulk of what it adds over a plain WebdriverIO setup. Verify first that your existing tests can be moved in without rewriting the assertions, that the browser and driver versions you need are supported, and that the sharding and grid setup matches the size of your suite.

## FAQ

### How do I set up a new testplane project?

Run the CLI wizard with `npm init testplane@latest new-testplane-project`, which sets up testplane and generates a basic configuration and a test file at testplane-tests/example.testplane.ts. If you prefer a manual install, use `npm i -D testplane` instead.

### What is the difference between testplane and hermione?

Testplane is the renamed Hermione, changed because of copyright and trademark issues. Since the rename was treated as a rebranding, the version count continued, so Testplane v8.x is a drop-in replacement for Hermione v8.x, and the v8 line is still receiving patch releases.

### How do visual assertions work in testplane?

You call the assertView command on an element, for example `await description.assertView("description")`, where the string is the name of the assertion and the identity of the reference image. The first run fails because no reference exists, you accept the diff, and the test then passes.

### Can testplane run unit tests in a real browser?

Yes. The README states you can run tests not only in a Node.js environment but also in the browser, so end to end and integration tests can run in Node.js while component or unit tests run in the browser. The component testing documentation is marked experimental.

### What license is testplane released under?

MIT, with the LICENSE file at the repository root and a license badge for the npm package.

## Sources

- [gemini-testing/testplane on GitHub](https://github.com/gemini-testing/testplane)
- [License: MIT](https://github.com/gemini-testing/testplane/blob/master/LICENSE)
- [Project website](https://testplane.io)
- [README](https://github.com/gemini-testing/testplane/blob/master/README.md)
- [Releases](https://github.com/gemini-testing/testplane/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gemini-testing-testplane