Jackrabbit-js

Write tests without dependencies (including jackrabbit itself).

Install

Install jackrabbit with npm.

npm install --save-dev @w-lfpup/jackrabbit

Or Install jackrabbit directly from github.

npm install --save-dev https://github.com/w-lfpup/jackrabbit-js

Tests

For a quick visual reference, please refer to the examples.

Developers with javascript experience can immediately start testing with basically zero overhead.

Tests

Tests are functions or promises that return assertions.

Tests pass when they return the undefined primitive or an empty array [].

// my.tests.ts

function testStuffAndPass() {
	return;
}

function testMoreStuffAndPass() {
	return [];
}

Any other value will cause a test to fail.

So tests that fail look like:

// my.tests.ts

function testStuffAndFail() {
	return "this test failed!";
}

function testMoreStuffAndFail() {
	return ["this test also failed!"];
}

Test Modules

Test Modules are javascript modules that export two values: tests and options.

Export Tests

Test Modules export their tests in an array called tests.

// my.tests.ts

export const tests = [
	testStuffAndPass,
	testMoreStuffAndPass,
	testStuffAndFail,
	testMoreStuffAndFail,
];

Export Options

Export a parameter object named options to affect test behaviors in the current module:

// my.tests.ts

interface Options {
  runAsynchronously?: boolean;
  timeoutMs?: number;
  title?: string;
}

...

export const options = {
	runAsyncronously: true,
	timeoutMs: 3000,
	title: import.meta.url,
}

All properties are optional and exporting an options pojo is not required.

Tests run sequentially unless the runAsyncronously property is set to true.

Test Collections

A test collection is a javascript module that exports a list test modules called testModules.

// mod.test.ts

import * as MyTests from "./my.tests.ts";

export const testModules = [
	MyTests
];

Run Test Collections

NodeJS

Run the following command to log the results of a test collection in nodejs.

npx jackrabbit ./mod.tests.ts

To run multiple test collections, add more filepaths as commandline arguments:

npx jackrabbit ./mod.tests.ts ./another_mod.tests.ts

Webdrivers

Jackrabbit can run tests in browsers via webdrivers. However, weebdrivers require a configuration file.

An example jackrabbit_webdriver config is as follows:

{
	"jackrabbit_url": "http://localhost:4000",
	"run_asynchronously": false,
	"webdrivers": [
		{
			"title": "Firefox",
			"command": "geckodriver -p 4001",
			"timeout_ms": 20000,
			"url": "http://localhost:4001",
			"capabilities": {
				"alwaysMatch": {
					"moz:firefoxOptions": {
						"args": ["-headless"]
					}
				}
			}
		}
	]
}

Run the following command to log the results of a test collection from a browser.

npx jackrabbit_webdriver ./config.json ./mod.tests.ts

To run multiple test collections, add more filepaths as commandline arguments:

npx jackrabbit_webdriver ./config.json ./mod.tests.ts ./another_mod.tests.ts

Webdriver commands

The following webdriver commands are available

Find element

Find an element id with a css selector.

import { findElement } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let elementId: string | undefined = await findElement("p");

Find elements

Find all element ids matching a css selector.

import { findElements } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let elementIds: string[] = await findElements("input[checkbox]");

Find element from element

Find all descendant element ids matching a css selector.

import { findElementFromElements } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let elementId: string | undefined = await findElementFromElements(
	"<element_id>",
	"input[checkbox]",
);

Find elements from element

Find all descendant element ids matching a css selector.

import { findElementsFromElements } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let elementIds: string[] = await findElementsFromElements(
	"<element_id>",
	"input[checkbox]",
);

Get element shadow root

If available, get the shadow root id of an element with an id

import { getElementShadowRoot } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let shadowRootId: string | undefined = await getElementShadowRoot(elementId);

Find element from shadow root

Find all descendant element ids matching a css selector.

import { findElementFromShadowRoot } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let elementId: string | undefined = await findElementFromShadowRoot(
	"<element_id>",
	"input[checkbox]",
);

Find elements from shadow root

Find all descendant element ids matching a css selector.

import { findElementsFromShadowRoot } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

let elementIds: string[] = await findElementsFromShadowRoot(
	"<element_id>",
	"input[checkbox]",
);

Take element screenshot

Get a screenshot of an element with their element id and save it to disk.

import { takeElementScreenshot } from "@w-lfpup/jackrabbit/browser/dist/mod.js";

await takeElementScreenshot(elementId, "./path/relative/to/cwd.png");

License

Jackrabbit-js is released under the BSD 3-Clause License.