geisterbahn v2.6.1

geisterbahn

web testing atomation utility for Puppeteer

What Is This?

geisterbahn is a utility which allows you to run headless browser automation tests using GoogleChrome/puppeteer.

Why Does It Exist?

On n'est jamais servi si bien que par soi-même

- Charles-Guillaume Étienne, 1807

How Does It Work?

Installation

yarn add geisterbahn or npm i geisterbahn or clone and install packages manually and go nuts?

CLI Usage

After installing, run ./node_modules/.bin/geisterbahn help; that should help. In case it doesn't help enough, I'll go over some of the options in more detail here.

geisterbahnfile.js

The geisterbahnfile is a configuration map you can use to store stage-specific settings, such as the stage's Base URL and basic auth credentials. In order to get started quickly, copy geisterbahnfile.js from this repository and adjust the values in there to your needs.

The -e, --environment parameter used in the CLI documentation up there references the keys used in your geisterbahnfile. If not specified, geisterbahn will look for the default environment to use in geisterbahnfile.js and yell at you if it doesn't find one there, either.

Another neat thing to know is that you can run any (synchronous) JavaScript code in your geisterbahnfile, such as reading environment variables, making blocking HTTP requests and all that jazz.

Tests

Let's get to the meat of things. Place your test packages in a directory, pass the -T, --test-source parameter to the CLI and fire away. But what does a test look like, tho?

module.exports = {
  title: "Home Page",
  definition: test => {
    test("headline is correct", async page => {
      await page.goto("/");
      const pageTitle = await page.getHtml("h1");
      if(pageTitle !== "Best Website Ever") {
        throw new Error("this is the worst day ever");
      }
    });
    test("headline is really correct", async page => {
      const pageTitle = await page.getHtml("h1");
      if(pageTitle !== "Super Best Website Ever") {
        throw new Error("oh no, not again!");
      }
    });
  }
}

Like this.

So, a test file is just a POJSO (plain old JS-object) with two important keys: title is a human readable title for your package o' tests, whereas definition is a function containing the tests themselves.

definition is passed two arguments: An object named page and a function named test.

If you export an array of objects formatted like this, geisterbahn will treat each entry as a separate test package.

Page Object

page is basically just an instance of Puppeteer's Page, however slightly modified in a small number of ways, which I'll go into a bit of detail about right now.

Test Function

test is a function that takes two parameters: A human readable string description of the second parameter, which is an async function containing test logic.

Write all your tests and page movements wrapped inside of one of those functions, and please, do not write them like I did in that example. Use an assertion library instead.

Partial Tests

geisterbahn sports a recursive partial test system, meaning that tests can be entirely or partially comprised of partials, which in turn can also be comprised of partials, and so on and so forth. Provided you don't abuse this power and compose evil circle dependencies, this can be used as a powerful tool in order to prevent copy-pasting test definitions over and over again for complex test cases.

Long story short, let's have an example! If you have a test like this:

//homepage.js
const assert = require('assert');
module.exports = {
  title: "Home Page",
  definition: test => {
    test("headline is correct", async page => {
      await page.goto("/");
      const pageTitle = await page.getHtml("h1");
      assert(pageTitle === "Best Website Ever");
    });
  }
}

And you want to write a test that also takes place on your home page, but you don't feel like repeating yourself, you could write a test that looks a little something like this:

//homepage_subheadline.js
const assert = require('assert');
module.exports = {
  title: "Home Page and Subheadline",
  partials: ['homepage'],
  definition: test => {
    test("subheadline is correct", async page => {
      await page.goto("/");
      const pageSubheadline = await page.getHtml("h2");
      assert(pageSubheadline === "It really is the Best Website Ever");
    });
  }
}

The above definition would execute the definition of homepage.js first, as if it were part of homepage_subheadline.js. Coupled with the fact that geisterbahn only autoloads tests that don't start with an underscore, you can see where I might be going with this.

Development / Contributing

What? Oh. Open Source Software. I get it. Yeah. Well, geisterbahn is still very much in active development right now, and there's tons I need to figure out before even trying to get into that whole scene. There's probably gonna be some sort of documentation on how to develop / contribute to this project. It's relatively straightforward to get into. I'm not gonna make any promises regarding issues and/or pull requests yet, tho. I'll try to be good about those.

Version History

2.5.0

• added -E option: stop on first error

2.4.2

• actually fixed CTRL+C behavior

2.4.1

• fixed CTRL+C behavior

2.4.0

• bumped puppeteer version to 1.2.0
• added more flexible mocking capabilities
• better handling of interrupts (CTRL+C, closing the browser window)

2.3.1

• disable automatic clearing of response mocks

2.3.0

• added option to export test definitions as array

2.2.0

• added -S, --slow-mo option
• added page.hitBackButton() augmentation for single page application testing

2.1.0

• added response mocking page augmentation

2.0.0

• changed defintion and test function signature: this update will break all of your tests, hooray!
• browser now closes and re-opens after every test package has run, making tests much more consistent
• require-cached versions of tests and partials are now discarded, making tests EVEN MORE consistent
• introduced --devtools option

1.4.1

• addded possibility to inject arguments into test partials

1.4.0

• discarded simple test dependency management
• introduced more complex partial system

1.3.0

• introduced simple test dependency management (undocumented for the time being)
• rewrote lots of loader code
• fixed attempts to autoload non-readable test files

1.2.0

• introduced cli option -l

1.1.1

• fixed a feature-breaking typo. woe is me.

1.1.0

• removed unnecessary (in hindsight) interactive option that was broken by 1.0.0 anyways
• added much more useful -b option

1.0.0

• bumped puppeteer version to 1.0.0
• changed definition function from async to sync
• changed test function from async to stack-based
• introduced clickAndWait helper function

0.5.0

• removed basic auth configuration from geisterbahnfile
• instead added additional header configuration to geisterbahnfile, which is much more handy
• added test directory and default environment config parameters to geisterbahnfile
• made a few error messages a bit more verbose
• fixed a very annoying grammatical error in README.md

0.4.0

• Initial release