docs: improve api documentation

README.md

@@ -12,7 +12,7 @@ Reliable, zero configuration end-to-end testing in BDD-style.
 [![Example][10]][13]
 
 ```ts
-import {browser, defineElement, it, test} from 'cybernaut';
+const {browser, defineElement, it, test} = require('cybernaut');
 
 test('Star the "clebert/cybernaut" repository on GitHub', async t => {
   await t.perform(browser.loadPage('https://github.com/clebert/cybernaut'));
@@ -87,7 +87,8 @@ The following configuration is active by default:
   "exclude": ["**/node_modules/**/*"],
   "include": "**/*.e2e.js",
   "retries": 4,
-  "retryDelay": 500
+  "retryDelay": 500,
+  "screenshotDirectory": "screenshots"
 }
 ```
 
@@ -128,22 +129,32 @@ If you write your tests with [TypeScript][18], it is recommended to enable the [
 ## API
 
 * [Test](#test)
+  * [test](#test)
+  * [skip](#skip)
+  * [assert](#assert)
+  * [perform](#perform)
+  * [verify](#verify)
+  * [fail](#fail)
+  * [pass](#pass)
 * [Browser](#browser)
+  * [pageTitle](#pagetitle)
+  * [pageUrl](#pageurl)
 * [Element](#element)
 * [PredicateBuilder](#predicatebuilder)
 
 ### Test
 
-#### Factory Functions
+#### `test`
 
-##### test
+Type definition:
 
-`test(name: string, implementation?: Implementation): void`
+- **`test(name: string, implementation?: Implementation): void`**
+- `Implementation = (t: Test) => Promise<void>`
 
-`type Implementation = (t: Test) => Promise<void>`
+Example usage:
 
 ```ts
-import {test} from 'cybernaut';
+const {test} = require('cybernaut');
 
 test('foo'); // This test will be marked as TODO
 
@@ -152,86 +163,167 @@ test('foo', async t => { // This test will be executed
 });
 ```
 
-##### skip
+#### `skip`
 
-`skip(name: string, implementation: Implementation): void`
+Type definition:
 
-`type Implementation = (t: Test) => Promise<void>`
+- **`skip(name: string, implementation: Implementation): void`**
+- `Implementation = (t: Test) => Promise<void>`
+
+Example usage:
 
 ```ts
-import {skip} from 'cybernaut';
+const {skip} = require('cybernaut');
 
 skip('foo', async t => { // This test won't be executed (and marked as SKIP)
   // ...
 });
 ```
 
-#### Methods
+#### `assert`
+
+Type definition: **`assert<T>(accessor: Accessor<T>, predicate: Predicate<T>, retries?: number, retryDelay?: number): Promise<void>`**
+
+Example usage:
+
+```ts
+const {browser, test} = require('cybernaut');
+
+test('foo', async t => {
+  await t.assert(browser.pageTitle, it.should.contain('bar')); // Throws an error if the condition isn't met
+});
+```
+
+#### `perform`
+
+Type definition: **`perform(action: Action, retries?: number, retryDelay?: number): Promise<void>`**
+
+Example usage:
+
+```ts
+const {browser, test} = require('cybernaut');
+
+test('foo', async t => {
+  await t.perform(browser.loadPage('http://bar.baz')); // Throws an error if the action fails
+});
+```
+
+#### `verify`
 
-##### assert
+Type definition: **`verify<T>(accessor: Accessor<T>, predicate: Predicate<T>, retries?: number, retryDelay?: number): Promise<boolean>`**
 
-`t.assert<T>(accessor: Accessor<T>, predicate: Predicate<T>, retries?: number, retryDelay?: number): Promise<void>`
+Example usage:
 
-##### perform
+```ts
+const {browser, test} = require('cybernaut');
 
-`t.perform(action: Action, retries?: number, retryDelay?: number): Promise<void>`
+test('foo', async t => {
+  if (await t.verify(browser.pageTitle, it.should.contain('bar'))) { // Evaluates to false if the condition isn't met
+    // ...
+  }
+});
+```
 
-##### verify
+#### `fail`
+
+Type definition: **`fail(message: string, cause: Error): void`**
+
+Example usage:
+
+```ts
+const {test} = require('cybernaut');
+
+test('foo', async t => {
+  t.fail('bar', new Error('baz')); // Throws a new error 'Error: bar (cause: baz)'
+});
+```
 
-`t.verify<T>(accessor: Accessor<T>, predicate: Predicate<T>, retries?: number, retryDelay?: number): Promise<boolean>`
+#### `pass`
 
-##### fail
+Type definition: **`pass(message: string): void`**
 
-`t.fail(message: string, cause: Error): void`
+Example usage:
 
-##### pass
+```ts
+const {test} = require('cybernaut');
 
-`t.pass(message: string): void`
+test('foo', async t => {
+  t.pass('bar'); // Prints a successful-test line in TAP format on standard output
+});
+```
 
 ### Browser
 
-#### Factory Function
+#### `pageTitle`
+
+Type definition: **`pageTitle: Accessor<string>`**
 
-##### browser
+Example TAP output: `ok 1 - page title should contain 'bar' (attempt 1 of 5)`
 
-`browser: Browser`
+Example usage:
 
 ```ts
-import {browser} from 'cybernaut';
+const {browser, test} = require('cybernaut');
+
+test('foo', async t => {
+  await t.assert(browser.pageTitle, it.should.contain('bar'));
+});
 ```
 
-#### Accessors
+#### `pageUrl`
+
+Type definition: **`pageUrl: Accessor<string>`**
+
+Example TAP output: `ok 1 - page url should contain 'http://bar.baz' (attempt 1 of 5)`
+
+Example usage:
+
+```ts
+const {browser, test} = require('cybernaut');
+
+test('foo', async t => {
+  await t.assert(browser.pageUrl, it.should.contain('http://bar.baz'));
+});
+```
 
-##### pageTitle
+#### `windowX`
 
-`browser.pageTitle: Accessor<string>`
+Type definition: **`windowX: Accessor<number>`**
 
-##### pageUrl
+Test output: `window x-position should ...`
 
-`browser.pageUrl: Accessor<string>`
+#### `windowY`
 
-##### windowX
+Type definition: **`windowY: Accessor<number>`**
 
-`browser.windowX: Accessor<number>`
+Test output: `window y-position should ...`
 
-##### windowY
+#### `windowWidth`
 
-`browser.windowY: Accessor<number>`
+Type definition: **`windowWidth: Accessor<number>`**
 
-##### windowWidth
+Test output: `window width should ...`
 
-`browser.windowWidth: Accessor<number>`
+#### `windowHeight`
 
-##### windowHeight
+Type definition: **`windowHeight: Accessor<number>`**
 
-`browser.windowHeight: Accessor<number>`
+Test output: `window height should ...`
 
-##### scriptResult
+#### `scriptResult`
+
+##### Typing:
 
 `browser.scriptResult(scriptName: string, script: Script): Accessor<any>`
 
 `type Script = (callback: (result?: any) => void) => void`
 
+##### Output:
+
+`result of script 'foo' should equal 'bar'`
+
+Example:
+
 ```ts
 await t.assert(browser.scriptResult('foo', callback => { // This script will be executed in the browser
   // ...
@@ -288,6 +380,18 @@ await t.perform(browser.executeScript('foo', callback => { // This script will b
 
 `browser.sleep(duration: number): Action`
 
+##### takeScreenshot
+
+`browser.takeScreenshot(): Action`
+
+Screenshots werden in das per konfigurierte `screenshotDirectory` gespeichert.
+Wenn der Pfad zum Screenshot Directory nicht absolut ist, wird er relativ zum CWD aufgelöst.
+Screenshots: `screenshots/<uuid>.png`
+
+Output:
+
+- `take screenshot 'screenshots/71af286f-cf75-4786-a6d3-fc8c858e22fe.png'`
+
 ### Element
 
 #### Factory Function
@@ -297,7 +401,7 @@ await t.perform(browser.executeScript('foo', callback => { // This script will b
 `defineElement(selector: string): Element`
 
 ```ts
-import {defineElement} from 'cybernaut';
+const {defineElement} = require('cybernaut');
 
 const element = defineElement('#foo');
 ```
@@ -367,7 +471,7 @@ const element = defineElement('#foo');
 `it: {should: PredicateBuilder}`
 
 ```ts
-import {it} from 'cybernaut';
+const {it} = require('cybernaut');
 ```
 
 #### Predicates

src/index.ts

@@ -44,7 +44,7 @@ class TapTest extends Test {
   }
 
   public fail(message: string, cause: Error): void {
-    throw new Error(`${message} (Cause: ${cause.message})`);
+    throw new Error(`${message} (cause: ${cause.message})`);
   }
 
   public pass(message: string): void {