nightwatch
Version:
Easy to use Node.js based end-to-end testing solution for web applications using the W3C WebDriver API.
673 lines (622 loc) • 17.5 kB
TypeScript
import {NightwatchCustomAssertions} from './custom-assertion';
import {Awaitable, Definition, ElementResult, JSON_WEB_OBJECT, ScopedSelector} from './index';
import { IfUnknown } from './utils';
export interface NightwatchAssertionsError {
name: string;
message: string;
showDiff: boolean;
stack: string;
}
export interface NightwatchCommonAssertions<ReturnType> {
/**
* Checks if the given attribute of an element contains the expected value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.attributeContains('#someElement', 'href', 'google.com');
* };
* ```
*/
attributeContains(
selector: Definition,
attribute: string,
expected: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given attribute of an element has the expected value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.attributeEquals('body', 'data-attr', 'some value');
* };
* ```
*/
attributeEquals(
selector: Definition,
attribute: string,
expected: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Check if an element's attribute value matches a regular expression.
*
* @example
*
* ```
* this.demoTest = function (browser) {
* browser.assert.attributeMatches('body', 'data-attr', '(value)');
* };
* ```
*
*/
attributeMatches(
selector: Definition,
attribute: string,
regex: string | RegExp,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the specified css property of a given element has the expected value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.cssProperty('#main', 'display', 'block');
* };
* ```
*/
cssProperty(
selector: Definition,
cssProperty: string,
expected: string,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the specified DOM property of a given element has the expected value.
* For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
* Several properties can be specified (either as an array or command-separated list). Nightwatch will check each one for presence.
*/
domPropertyContains(
selector: Definition,
domProperty: string,
expected: string | number,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<any>>;
/**
* Checks if the specified DOM property of a given element has the expected value.
* For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
* If the result value is JSON object or array, a deep equality comparison will be performed.
*/
domPropertyEquals(
selector: Definition,
domProperty: string,
expected: string | number,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<any>>;
/**
* Check if specified DOM property value of a given element matches a regex.
* For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
*/
domPropertyMatches(
selector: Definition,
domProperty: string,
expected: string | RegExp,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<any>>;
/**
* Checks if the number of elements specified by a selector is equal to a given value.
*
* @example
*
* this.demoTest = function (browser) {
* browser.assert.elementsCount('div', 10);
* browser.assert.not.elementsCount('div', 10);
* }
*
*/
elementsCount(
selector: ScopedSelector,
count: number,
msg?: string
): Awaitable<
IfUnknown<ReturnType, this>,
NightwatchAssertionsResult<JSON_WEB_OBJECT[]> & {
WebdriverElementId: string;
}
>;
/**
* Checks if the given element exists in the DOM.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.elementPresent("#main");
* };
* ```
*/
elementPresent(
selector: ScopedSelector,
msg?: string
): Awaitable<
IfUnknown<ReturnType, this>,
NightwatchAssertionsResult<ElementResult[]>
>;
/**
* Checks if the given element does not exists in the DOM.
*
* @example
* ```
* this.demoTest = function (browser) {
* browser.assert.elementNotPresent(".should_not_exist");
* };
* ```
*
* @deprecated In favour of `assert.not.elementPresent()`.
*/
elementNotPresent(
selector: Definition,
msg?: string
): Awaitable<
IfUnknown<ReturnType, this>,
NightwatchAssertionsResult<ElementResult[]>
>;
/**
* Checks if the given element does not have the specified CSS class.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.cssClassNotPresent('#main', 'container');
* };
* ```
*
* @deprecated In favour of `assert.not.hasClass()`.
*/
cssClassNotPresent(
selector: Definition,
className: string,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given element has the specified CSS class.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.cssClassPresent('#main', 'container');
* };
* ```
*
* @deprecated In favour of `assert.hasClass()`.
*/
cssClassPresent(
selector: Definition,
className: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given element has the specified CSS class.
*
* @example
*
*
* ```
* this.demoTest = function (browser) {
* browser.assert.hasClass('#main', 'container');
* browser.assert.hasClass('#main', ['visible', 'container']);
* browser.assert.hasClass('#main', 'visible container');
* };
* ```
*
*/
hasClass(
selector: Definition,
className: string | string[],
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given element contains the specified DOM attribute.
*
* Equivalent of: https://developer.mozilla.org/en-US/docs/Web/API/Element/hasAttribute
*
* @example
*
* ```
* this.demoTest = function (browser) {
* browser.assert.hasAttribute('#main', 'data-track');
* };
* ```
*
*/
hasAttribute(
selector: Definition,
expectedAttribute: string,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given element is enabled (as indicated by the 'disabled' attribute).
*
* @example
* this.demoTest = function (browser) {
* browser.assert.enabled('.should_be_enabled');
* browser.assert.enabled({selector: '.should_be_enabled'});
* browser.assert.enabled({selector: '.should_be_enabled', suppressNotFoundErrors: true});
* };
*/
enabled(
selector: Definition,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<boolean>>;
/**
* Checks if the given element is selected.
*
* @example
* this.demoTest = function (browser) {
* browser.assert.selected('.should_be_selected');
* browser.assert.selected({selector: '.should_be_selected'});
* browser.assert.selected({selector: '.should_be_selected', suppressNotFoundErrors: true});
* };
*/
selected(
selector: Definition,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<boolean>>;
/**
* Checks if the given element contains the specified text.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.containsText('#main', 'The Night Watch');
* };
* ```
*
* @deprecated In favour of `assert.textContains()`.
*/
containsText(
selector: Definition,
expectedText: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given element contains the specified text.
*
* @example
* ```
* this.demoTest = function (browser) {
* browser.assert.textContains('#main', 'The Night Watch');
* };
* ```
*
*/
textContains(
selector: Definition,
expectedText: string,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Check if an element's inner text equals the expected text.
*
* @example
*
* ```
* this.demoTest = function (browser) {
* browser.assert.textEquals('#main', 'The Night Watch');
* };
* ```
*
*/
textEquals(
selector: Definition,
expectedText: string,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Check if an elements inner text matches a regular expression.
*
* @example
*
* ```
* this.demoTest = function (browser) {
* browser.assert.textMatches('#main', '^Nightwatch');
* };
* ```
*
*/
textMatches(
selector: Definition,
regex: string | RegExp,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the page title equals the given value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.title("Nightwatch.js");
* };
* ```
*
* @deprecated In favour of `titleEquals()`.
*/
title(
expected: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the page title equals the given value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.title("Nightwatch.js");
* };
* ```
*/
titleContains(
expected: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the page title equals the given value.
* @since 2.0
* ```
* this.demoTest = function (browser) {
* browser.assert.titleEquals("Nightwatch.js");
* };
* ```
*/
titleEquals(
expected: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the current title matches a regular expression.
*
* @example
*
* ```
* this.demoTest = function (browser) {
* browser.assert.titleMatches('^Nightwatch');
* };
* ```
*
*/
titleMatches(
regex: string | RegExp,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the current URL contains the given value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.urlContains('google');
* };
* ```
*/
urlContains(
expectedText: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the current url equals the given value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.urlEquals('https://www.google.com');
* };
* ```
*/
urlEquals(
expected: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the current url matches a regular expression.
*
* @example
* ```
* this.demoTest = function (browser) {
* browser.assert.urlMatches('^https');
* };
* ```
*
*/
urlMatches(
regex: string | RegExp,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given form element's value equals the expected value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.value("form.login input[type=text]", "username");
* };
* ```
*
* @deprecated In favour of `assert.valueEquals()`.
*/
value(
selector: Definition,
expectedText: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given form element's value contains the expected value.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.valueContains("form.login input[type=text]", "username");
* };
* ```
*/
valueContains(
selector: Definition,
expectedText: string,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given form element's value equals the expected value.
*
* The existing .assert.value() command.
*
* @example
* ```
* this.demoTest = function (browser) {
* browser.assert.valueEquals("form.login input[type=text]", "username");
* };
* ```
*
*/
valueEquals(
selector: Definition,
expected: string,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<string>>;
/**
* Checks if the given element is not visible on the page.
*
* @example
* ```
* this.demoTest = function (browser) {
* browser.assert.hidden('.should_not_be_visible');
* };
* ```
*
* @deprecated In favour of `assert.not.visible()`.
*/
hidden(
selector: Definition,
msg?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<boolean>>;
/**
* Checks if the given element is visible on the page.
*
* ```
* this.demoTest = function (browser) {
* browser.assert.visible(".should_be_visible");
* };
* ```
*/
visible(
selector: Definition,
message?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchAssertionsResult<boolean>>;
NightwatchAssertionsError: NightwatchAssertionsError;
}
export interface NightwatchNodeAssertionsResult {
value: null;
returned: 1;
}
export interface NightwatchNodeAssertions<ReturnType> {
// The following definitions are taken from @types/assert
fail(
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
fail(
actual: any,
expected: any,
message?: string | Error,
operator?: string
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
ok(
value: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
equal(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
notEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
deepEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
notDeepEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
strictEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
notStrictEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
deepStrictEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
notDeepStrictEqual(
actual: any,
expected: any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
throws(
block: () => any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
doesNotThrow(
block: () => any,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
ifError(
value: any
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
rejects(
block: (() => Promise<any>) | Promise<any>,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
doesNotReject(
block: (() => Promise<any>) | Promise<any>,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
match(
value: string,
regExp: RegExp,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
doesNotMatch(
value: string,
regExp: RegExp,
message?: string | Error
): Awaitable<IfUnknown<ReturnType, this>, NightwatchNodeAssertionsResult | Error>;
}
export interface NightwatchAssertions<ReturnType>
extends NightwatchCommonAssertions<ReturnType>,
NightwatchCustomAssertions<ReturnType> {
/**
* Negates any of assertions following in the chain.
*/
not: Omit<NightwatchAssertions<ReturnType>, 'not'>;
}
export interface NightwatchAssertionsResult<T> {
value: T;
status: 0;
returned: 1;
passed: true;
}
export interface Assert<ReturnType = unknown>
extends NightwatchAssertions<ReturnType>,
NightwatchNodeAssertions<ReturnType> { }
// TODO: Check where the following type is being used.
/**
* Performs an assertion
*
*/
export type NightwatchAssert = (
passed: boolean,
receivedValue?: any,
expectedValue?: any,
message?: string,
abortOnFailure?: boolean,
originalStackTrace?: string
) => void;