Grok JS Marker (Puppeteer) API v1.0 Class: TestCaseAPI

new TestCaseAPI()

Example

// An instance of the api is passed to your runTest function:
function runTest(api) {
  // Use the api as needed, e.g.:
  api.pass();
}

// Or to your runBeforeLoad function, if defined:
function runBeforeLoad(api) {
  api.expectDialog('alert', {message: 'USER: alert'});
}

module.exports = {runBeforeLoad, runTest};

Methods

<static> format(text [, options])

Formats text for a failure report.

Parameters:

Name Type Argument Description

text

string

Some short paragraph or string to render in a terminal-like block.

options

Object

Properties

Name	Type	Argument	Description
`lang`	string	<optional>	Sets the 'data-lang' attribute on the `<code></code>` block. Defaults to 'html'
`block`	boolean	<optional>	[false] Enclose the text within a `<pre class="js-terminal"></pre>` block
`safe`	boolean	<optional>	[false] Preserve the HTML formatting within the text by marking it as safe (otherwise we escape).
`default`	boolean	<optional>	[`text.toString()`] Default if the text provided is "falsy" (null, undefined or an empty string).

Returns:

Formatted text.

Type: BaseString

<static> formatAttr(attr)

Formats the value like an HTML Element attribute, inline.

Parameters:

Name	Type	Description
`attr`	string	Attribute, e.g. 'src' or 'onsubmit'

Returns:

Formatted attribute text.

Type: BaseString

<static> formatBlock(text [, options])

Formats a block of text for a failure report.

Parameters:

Name Type Argument Description

text

string

Some short paragraph or string to render in a terminal-like block.

options

Object

Properties

Name	Type	Argument	Description
`lang`	string	<optional>	Sets the 'data-lang' attribute on the `<code></code>` block. Defaults to 'html'

Returns:

Formatted block.

Type: BaseString

<static> formatJavascript(js)

Formats the name of a javascript variable, or perhaps a short snippet of javascript code (inline).

Parameters:

Name	Type	Description
`js`	string	Variable name or code snippet, e.g. 'querySelector()'

Returns:

Formatted text.

Type: BaseString

<static> formatLiteral(value)

Formats the value of a javascript variable, as a block, according to the type.

Parameters:

Name	Type	Description
`value`	any

Returns:

Formatted value.

Type: BaseString

<static> formatString()

Formats the text as a short string, including double quotes.

Returns:

Formatted text.

Type: BaseString

<static> formatStyle(name)

Formats the name of a CSS style property, such as 'color', 'border-right', etc.

Parameters:

Name	Type	Description
`name`	string

Returns:

Formatted text.

Type: BaseString

<static> formatStyleValue(value)

Converts the value of a CSS property into a normalised view, taking care of alternate names for colours, etc.

Parameters:

Name	Type	Description
`value`	string	A CSS style value, e.g. 'rgb(0, 0, 0)' or '50px'.

Returns:

Formatted version, with colors converted to names if we know them.

Type: BaseString

<static> formatTag(tag)

Create an inline block to highlight an html tag name (or similar).

Parameters:

Name	Type	Description
`tag`	string

Returns:

Formatted tag name.

Type: BaseString

<static> msg(parts)

Construct a BaseString message from a series of string-like parts.

Parameters:

Name	Type	Argument	Description
`parts`	string \| BaseString \| *	<repeatable>	Arguments provided like for `console.log()`. Any non-string types will be converted to an UnsafeString, except for BaseString objects.

Returns:

Type: BaseString

<static> numToCard(i)

Get the cardinal number, eg. numToCard(9) -> 'nine'.

Parameters:

Name	Type	Description
`i`	number

Returns:

Cardinal representation.

Type: string

<static> numToOrd(i)

Get the ordinal of a number, eg. numToOrd(9) -> 'ninth'.

Parameters:

Name	Type	Description
`i`	number

Returns:

Ordinal representation.

Type: string

<static> rgbToColor(rgb)

Convert an rgb triple to a color name, if we have one.

Parameters:

Name	Type	Description
`rgb`	string	A string in the format 'rgb(r, g, b)'.

Returns:

A color name, if found, undefined, if not.

Type: string

<static> S(safe)

Wrap HTML formatted text with a 'safe' wrapper to indicate that it should not be escaped.

Parameters:

Name	Type	Argument	Description
`safe`	string \| BaseString \| *	<repeatable>	Arguments provided like for `console.log()`. Any non-string types will be converted to a SafeString, except for BaseString objects.

Returns:

Type: BaseString

Example

const msg = api.S('<b>Emphasise this</b>', formatBlock('preformatted'), 'plus', 6, 'trailing remarks');

<static> US(unsafe)

Wrap an HTML-unsafe string so that it will be escaped exactly once.

Parameters:

Name	Type	Argument	Description
`unsafe`	string \| BaseString \| *	<repeatable>	Arguments provided like for `console.log()`. Any non-string types will be converted to an UnsafeString, except for BaseString objects.

Returns:

Type: BaseString

Example

const msg = api.US('First & foremost', formatString('a literal'), 'plus', 6, 'trailing remarks');

addScriptTag(url [, selector])

Inject javascript into the page by adding a script tag to its source URL.

Parameters:

Name	Type	Argument	Default	Description
`url`	string			relative or absolute URL for the script to inject
`selector`	string	<optional>	head	['head'] Allows you to specify which element the script tag should go into (at the end). Best to use 'head' or 'body'.

addStyleTag(url [, atTop])

Inject a style sheet into the page by adding a link tag to its source URL into the HEAD of the document.

Parameters:

Name	Type	Argument	Default	Description
`url`	string			relative or absolute URL for the script to inject
`atTop`	Boolean	<optional>	false	[false] Specifies whether the link should go at the top (before first child) or at the bottom (appended) of the BODY.

debug(args)

Send a message to the driver debugger stream. This is not currently visible in the marker UI 'View Raw' at the moment, but it may be in the future, and is handy on the command-line unit-testing.

Parameters:

Name	Type	Argument	Description
`args`	*	<repeatable>	Just like you pass to console.log()

evaluate(fn, args)

Execute a function in the browser context.

Parameters:

Name	Type	Argument	Description
`fn`	PageFunction		Function to execute inside the user's page.
`args`	*	<repeatable>	Arguments to pass to the function.

Returns:

The result of the PageFunction.

Type: *

expectDialog(type [, options])

Inform the DialogManager that the next dialog should match the details provided, and to perform the given response. If there is no dialog expected when a dialog event occurs, our default handler is to fail the test case (to avoid blocking the page and thus the driver). This can be called from within a runBeforeLoad() function exposed in the test case module, to handle initial onload popups.

Parameters:

Name Type Argument Description

type

string

One of ['alert', 'prompt', 'confirm', 'beforeunload']

options

Object

Properties

Name	Type	Argument	Description
`message`	string	<optional>	This is the message that we expect to see as the prompt inside the dialog. Fails the test with no exact match, but only if defined.
`callback`	DialogCallback	<optional>	[null] Called when the dialog pops up, after validating the type and message. Use this to perform additional validation or pass the test case explicitly to avoid any further dialog handling.
`action`	boolean		['accept'] How to handle the alert, assuming it is valid. One of ['accept', 'dismiss'].
`response`	string	<optional>	[''] Valid only for 'prompt' type, this is the response that we will send back to the user page.

expectNoDialogsPending()

Checks that the dialogs have all been successfully dealt with, and fails the test with a report if there are some remaining.

expectNullVar(name [, options])

Check whether the variable with the given name is currently set to null. This is a special case of expectVar which you can use directly.

Parameters:

Name	Type	Argument	Description
`name`	string		Name of the variable to validate
`options`	Object	<optional>

expectVar(name, expected [, options])

Ensure a page variable matches the expected value, for variables that are simple types: [string, number, boolean, undefined]. For complex variables (functions, objects or symbols, etc.) you should retrieve the value with TestCaseAPI.getVar and perform checking manually. We have the opportunity here to validate the type of the variable, too. Differences in type will be reported in the details of the failure report.

Parameters:

Name Type Argument Description

name

string

Name of the variable to validate

expected

Expected value. We only check simple types [string, number, boolean, undefined]. If the student's value is some other type, we will fail the test with a generic message about what we expected.

options

Object

Properties

Name	Type	Argument	Description
`failure`	FailureReportOptions	<optional>

To Do:

FIXME The failure reporting here is all wacky. Need to nail this down too.

expectVars(expected [, options])

Ensure many page variables matches their expected value.

Parameters:

Name	Type	Argument	Description
`expected`	Object		Maps variable name to expected value. Simple types only (string, number, boolean, null or undefined) are checked, here. See also expectVar.
`options`	Object	<optional>

fail(reason [, options])

Immediately fail the test with a message.

Parameters:

Name	Type	Argument	Description
`reason`	string		Describe the reason for the failure.
`options`	FailureReportOptions	<optional>

fastForwardRaf(numIterations)

Play the user's animation by stepping through their intercepted requestAnimationFrame callbacks. This requires INTERCEPT_RAF to have been enabled on the test case.

Parameters:

Name	Type	Default	Description
`numIterations`	number	1	The number of calls to requestAnimationFrame() that we should perform.

getElement(selector, tag, aOrAn, description)

Fetches an element handle for the given selector, failing the test case if the selector is not available in the DOM. Use the api calls on the Element object to test state and interact with the element.

Parameters:

Name	Type	Description
`selector`	string
`tag`	string
`aOrAn`	string	precedes the description wherever we would refer to 'an element'.
`description`	string \| BaseString	describes the element in the singular, e.g. 'cookie element' or '"Add" button'. See example for special tag expansion.

Returns:

Type: Element

Example

// Use a string description and convert {tag} into a formatted tag name:
const element = api.getElement('h1', 'h1', 'a', 'heading {h1} element');
element.description === 'heading <code data-lang="tag">h1</code> element';

// Use a BaseString description to roll your own:
const element = api.getElement('h1', 'h1', 'a', api.S('heading', formatTag('h1'), 'element');
element.description === 'heading <code data-lang="tag">h1</code> element';

getElementGroup(selector, tag, aOrAn, description [, options])

Grabs an ElementGroup for the given selector, allowing you to count the number of observed elements, or test over a group of elements.

Parameters:

Name Type Argument Description

selector

string

identifies elements that will form the group

tag

string

an HTML tag associated with each element, e.g. 'li'

aOrAn

string

either 'a' or 'an' according to the following description argument (describes the singular element).

description

string | BaseString

describes a singular element. This will be pluralised by converting the first occurrence of /element/ into /elements/. See example for special tag expansion.

options

Object

Properties

Name	Type	Description
`plural`	string \| BaseString	plural form, if needed. {tag} substitution on strings will also work here.

Returns:

Type: ElementGroup

Example

// Use a string description and convert {tag} into a formatted tag name:
const group = api.getElementGroup('p.inner', 'p', 'a', '{p} element');
group.description === '<code data-lang="tag">p</code> element';
group.descriptionPlural === '<code data-lang="tag">p</code> elements';

// Use a BaseString description to roll your own:
const group = api.getElementGroup('p.inner', 'p', 'a', api.S(formatTag('p'), 'element');
group.description === '<code data-lang="tag">p</code> element';
group.descriptionPlural === '<code data-lang="tag">p</code> elements';

getFailedRequests()

Get a list of failed requests for user page resources, over the lifetime of the test.

Returns:

Type: Array.<FailedRequest>

getVar(name [, options])

Get the value of a variable (let, const, var) that is in the page scope.

Parameters:

Name Type Argument Description

name

string

name of the variable to fetch

options

Object

Properties

Name	Type	Argument	Description
`failIfMissing`	boolean	<optional>	[false] Set to true to fail the test if the variable name is not in the scope. Returns undefined, if this flag is not set.

Returns:

The value in the page scope - works best with primitives types like string, number, boolean or undefined. In v1.0 we will return a basic string description for more complex values (functions, objects and symbols).

Type: *

pass()

Immediately pass the test case and skip all remaining test checks and actions.

sleep(ms)

Sleep for a period of time.

Parameters:

Name	Type	Description
`ms`	number	number of milliseconds to block for.