From d75d0ebec869ff3c1a93bae388744b5489eb318c Mon Sep 17 00:00:00 2001 From: Clemens Akens Date: Mon, 3 Apr 2017 00:50:48 +0200 Subject: [PATCH] docs: improve api documentation --- README.md | 188 +++++++++++++++++++++++++++++++++++++++------------ src/index.ts | 2 +- 2 files changed, 147 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index c7b4906..cb4ec59 100644 --- a/README.md +++ b/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` -`type Implementation = (t: Test) => Promise` +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` +- **`skip(name: string, implementation: Implementation): void`** +- `Implementation = (t: Test) => Promise` + +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(accessor: Accessor, predicate: Predicate, retries?: number, retryDelay?: number): Promise`** + +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`** + +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(accessor: Accessor, predicate: Predicate, retries?: number, retryDelay?: number): Promise`** -`t.assert(accessor: Accessor, predicate: Predicate, retries?: number, retryDelay?: number): Promise` +Example usage: -##### perform +```ts +const {browser, test} = require('cybernaut'); -`t.perform(action: Action, retries?: number, retryDelay?: number): Promise` +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(accessor: Accessor, predicate: Predicate, retries?: number, retryDelay?: number): Promise` +#### `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`** -##### 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`** + +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` +Type definition: **`windowX: Accessor`** -##### pageUrl +Test output: `window x-position should ...` -`browser.pageUrl: Accessor` +#### `windowY` -##### windowX +Type definition: **`windowY: Accessor`** -`browser.windowX: Accessor` +Test output: `window y-position should ...` -##### windowY +#### `windowWidth` -`browser.windowY: Accessor` +Type definition: **`windowWidth: Accessor`** -##### windowWidth +Test output: `window width should ...` -`browser.windowWidth: Accessor` +#### `windowHeight` -##### windowHeight +Type definition: **`windowHeight: Accessor`** -`browser.windowHeight: Accessor` +Test output: `window height should ...` -##### scriptResult +#### `scriptResult` + +##### Typing: `browser.scriptResult(scriptName: string, script: Script): Accessor` `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/.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 diff --git a/src/index.ts b/src/index.ts index 8878a6c..e7c58a4 100644 --- a/src/index.ts +++ b/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 {