testcafe
Version:
Automated browser testing for the modern web development stack.
1,109 lines (1,059 loc) • 113 kB
TypeScript
declare module 'testcafe' {
global {
interface KeyModifiers {
ctrl?: boolean;
alt?: boolean;
shift?: boolean;
meta?: boolean;
}
interface CropOptions {
/**
* The top edge of the cropping rectangle. The coordinate is calculated from the element's top edge.
* If a negative number is passed, the coordinate is calculated from the element's bottom edge.
*/
left?: number;
/**
* The left edge of the cropping rectangle. The coordinate is calculated from the element's left edge.
* If a negative number is passed, the coordinate is calculated from the element's right edge.
*/
right?: number;
/**
* The bottom edge of the cropping rectangle. The coordinate is calculated from the element's top edge.
* If a negative number is passed, the coordinate is calculated from the element's bottom edge.
*/
top?: number;
/**
* The right edge of the cropping rectangle. The coordinate is calculated from the element's left edge.
* If a negative number is passed, the coordinate is calculated from the element's right edge.
*/
bottom?: number;
}
interface ActionOptions {
/**
* The speed of action emulation. Defines how fast TestCafe performs the action when running tests.
* A value between 1 (the maximum speed) and 0.01 (the minimum speed). If test speed is also specified in the CLI or
* programmatically, the action speed setting overrides test speed. Default is 1.
*/
speed?: number;
}
interface TakeScreenshotOptions {
/**
* Specifies the path where the screenshots are saved.
*/
path?: string;
/**
* Specifies that TestCafe should take full-page screenshots.
*/
fullPage?: boolean;
/**
* Specifies the custom naming pattern for the screenshot.
*/
pathPattern?: string;
}
interface TakeElementScreenshotOptions extends ActionOptions {
/**
* Allows to crop the target element on the screenshot.
*/
crop?: CropOptions;
/**
* Controls if element's margins should be included in the screenshot.
* Set this property to `true` to include target element's margins in the screenshot.
* When it is enabled, the `scrollTargetX`, `scrollTargetY` and `crop` rectangle coordinates are calculated from
* the corners where top and left (or bottom and right) margins intersect
*/
includeMargins?: boolean;
/**
* Controls if element's borders should be included in the screenshot.
* Set this property to `true` to include target element's borders in the screenshot.
* When it is enabled, the `scrollTargetX`, `scrollTargetY` and `crop` rectangle coordinates are calculated from
* the corners where top and left (or bottom and right) internal edges of the element intersect
*/
includeBorders?: boolean;
/**
* Controls if element's paddings should be included in the screenshot.
* Set this property to `true` to include target element's paddings in the screenshot.
* When it is enabled, the `scrollTargetX`, `scrollTargetY` and `crop` rectangle coordinates are calculated from
* the corners where top and left (or bottom and right) edges of the element's content area intersect
*/
includePaddings?: boolean;
/**
* Specifies the X coordinate of the scrolling target point.
* If the target element is too big to fit into the browser window, the page will be scrolled to put this point
* to the center of the viewport. The coordinates of this point are calculated relative to the target element.
* If the numbers are positive, the point is positioned relative to the top-left corner of the element.
* If the numbers are negative, the point is positioned relative to the bottom-right corner.
* If the target element fits into the browser window, these properties have no effect.
*/
scrollTargetX?: number;
/**
* Specifies the Y coordinate of the scrolling target point.
* If the target element is too big to fit into the browser window, the page will be scrolled to put this point
* to the center of the viewport. The coordinates of this point are calculated relative to the target element.
* If the numbers are positive, the point is positioned relative to the top-left corner of the element.
* If the numbers are negative, the point is positioned relative to the bottom-right corner.
* If the target element fits into the browser window, these properties have no effect.
*/
scrollTargetY?: number;
}
interface OffsetOptions extends ActionOptions {
/**
* Mouse pointer X coordinate that define a point where the action is performed or started.
* If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the target element.
* If an offset is a negative integer, they are calculated relative to the bottom-right corner.
* The default is the center of the target element.
*/
offsetX?: number;
/**
* Mouse pointer Y coordinate that define a point where the action is performed or started.
* If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the target element.
* If an offset is a negative integer, they are calculated relative to the bottom-right corner.
* The default is the center of the target element.
*/
offsetY?: number;
}
interface MouseActionOptions extends OffsetOptions {
/**
* Indicate which modifier keys are to be pressed during the mouse action.
*/
modifiers?: KeyModifiers;
}
interface ClickActionOptions extends MouseActionOptions {
/**
* The initial caret position if the action is performed on a text input field. A zero-based integer.
* The default is the length of the input field content.
*/
caretPos?: number;
}
interface TypeActionOptions extends ClickActionOptions {
/**
* `true` to remove the current text in the target element, and false to leave the text as it is.
*/
replace?: boolean;
/**
* `true` to insert the entire block of current text in a single keystroke (similar to a copy & paste function),
* and false to insert the current text character by character.
*/
paste?: boolean;
/**
* `true` to replace the typed text with a placeholder when sending action logs to a reporter.
*/
confidential?: boolean;
}
interface PressActionOptions extends ActionOptions {
/**
* `true` to replace the pressed keys with a placeholder when sending action logs to a reporter.
*/
confidential?: boolean;
}
interface DragToElementOptions extends MouseActionOptions {
/**
* Mouse pointer X coordinate that defines a point where the dragToElement action is finished.
* If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the destination element.
* If an offset is a negative integer, they are calculated relative to the bottom-right corner.
* By default, the dragToElement action is finished in the center of the destination element.
*/
destinationOffsetX?: number;
/**
* Mouse pointer Y coordinate that defines a point where the dragToElement action is finished.
* If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the destination element.
* If an offset is a negative integer, they are calculated relative to the bottom-right corner.
* By default, the dragToElement action is finished in the center of the destination element.
*/
destinationOffsetY?: number;
}
interface ResizeToFitDeviceOptions {
/**
* `true` for portrait screen orientation; `false` for landscape.
*/
portraitOrientation?: boolean;
}
interface CookieOptions {
/**
* The name of the cookie.
*/
name?: string;
/**
* The value of the cookie.
*/
value?: string;
/**
* The domain attribute of the cookie.
*/
domain?: string;
/**
* The path attribute of the cookie. The path must exist on the server to send the Cookie header.
*/
path?: string;
/**
* The date and time at which the cookie expires. The browser does not serve the cookie if the client clock is set to a point beyond the cookie expiration time.
*/
expires?: Date;
/**
* Cookie expiration time in seconds, relative to the time the cookie is served.
*/
maxAge?: number | 'Infinity' | '-Infinity';
/**
* If the "secure" attribute is "true", the browser only serves the cookie over HTTPS.
*/
secure?: boolean;
/**
* Prohibits client-side scripts from accessing the cookie. Helps prevent XSS attacks.
*/
httpOnly?: boolean;
/**
* Prohibits the browser from serving the cookie in response to cross-site requests. Helps prevent XSRF attacks.
*/
sameSite?: string;
}
interface AssertionOptions {
/**
* The amount of time, in milliseconds, allowed for an assertion to pass before the test fails if a
* selector property or a client function was used in assertion.
*/
timeout?: number;
/**
* By default, a Promise is not allowed to be passed to an assertion unless it is a selector property
* or the result of a client function. Setting this property to `true` overrides that default.
*/
allowUnawaitedPromise?: boolean;
}
interface Assertion<E = any> {
/**
* Asserts that `actual` is deeply equal to `expected`.
*
* @param expected - An expected value.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
eql(expected: E, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that actual is deeply equal to expected.
*
* @param expected - An expected value.
* @param options - Assertion options.
*/
eql(expected: E, options?: AssertionOptions): TestControllerPromise;
/**
* Assert that `actual` is not deeply equal to `unexpected`.
*
* @param unexpected - An unexpected value.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
notEql(unexpected: E, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Assert that `actual` is not deeply equal to `unexpected`.
*
* @param unexpected - An unexpected value.
* @param options - Assertion options.
*/
notEql(unexpected: E, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is truthy.
*
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
ok(message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is truthy.
*
* @param options - Assertion options.
*/
ok(options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is falsy.
*
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
notOk(message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is falsy.
*
* @param options - Assertion options.
*/
notOk(options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` contains `expected`.
*
* @param expected - An expected value.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
contains<R>(expected: EnsureString<E> | ElementOf<E> | Extend<E, R>, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` contains `expected`.
*
* @param expected - An expected value.
* @param options - Assertion options.
*/
contains<R>(expected: EnsureString<E> | ElementOf<E> | Extend<E, R>, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` not contains `unexpected`.
*
* @param unexpected - An unexpected value.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
notContains<R>(unexpected: EnsureString<E> | ElementOf<E> | Extend<E, R>, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` not contains `unexpected`.
*
* @param unexpected - An unexpected value.
* @param options - Assertion options.
*/
notContains<R>(unexpected: EnsureString<E> | ElementOf<E> | Extend<E, R>, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that type of `actual` is `typeName`.
*
* @param typeName - The expected type of an `actual` value.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
typeOf(typeName: 'function' | 'object' | 'number' | 'string' | 'boolean' | 'undefined' | 'null' | 'regexp', message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that type of `actual` is `typeName`.
*
* @param typeName - The expected type of an `actual` value.
* @param options - Assertion options.
*/
typeOf(typeName: 'function' | 'object' | 'number' | 'string' | 'boolean' | 'undefined' | 'null' | 'regexp', options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that type of `actual` is not `typeName`.
*
* @param typeName - An unexpected type of an `actual` value.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
notTypeOf(typeName: 'function' | 'object' | 'number' | 'string' | 'boolean' | 'undefined' | 'null' | 'regexp', message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that type of `actual` is not `typeName`.
*
* @param typeName - An unexpected type of an `actual` value.
* @param options - Assertion options.
*/
notTypeOf(typeName: 'function' | 'object' | 'number' | 'string' | 'boolean' | 'undefined' | 'null' | 'regexp', options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is strictly greater than `expected`.
*
* @param expected - A value that should be less than or equal to `actual`.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
gt(expected: number, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is strictly greater than `expected`.
*
* @param expected - A value that should be less than or equal to `actual`.
* @param options - Assertion options.
*/
gt(expected: number, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is greater than or equal to `expected`.
*
* @param expected - A value that should be less than `actual`.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
gte(expected: number, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is greater than or equal to `expected`.
*
* @param expected - A value that should be less than `actual`.
* @param options - Assertion options.
*/
gte(expected: number, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is less than `expected`.
*
* @param expected - A value that should be greater than or equal to `actual`.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
lt(expected: number, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is less than `expected`.
*
* @param expected - A value that should be greater than or equal to `actual`.
* @param options - Assertion options.
*/
lt(expected: number, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is less than or equal to `expected`.
*
* @param expected - A value that should be greater than `actual`.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
lte(expected: number, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is less than or equal to `expected`.
*
* @param expected - A value that should be greater than `actual`.
* @param options - Assertion options.
*/
lte(expected: number, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is within a range from `start` to `finish`. Bounds are inclusive.
*
* @param start - A lower bound of range (included).
* @param finish - An upper bound of range (included).
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
within(start: number, finish: number, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is within a range from `start` to `finish`. Bounds are inclusive.
*
* @param start - A lower bound of range (included).
* @param finish - An upper bound of range (included).
* @param options - Assertion options.
*/
within(start: number, finish: number, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is not within a range from `start` to `finish`. Bounds are inclusive.
*
* @param start - A lower bound of range (included).
* @param finish - An upper bound of range (included).
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
notWithin(start: number, finish: number, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` is not within a range from `start` to `finish`. Bounds are inclusive.
*
* @param start - A lower bound of range (included).
* @param finish - An upper bound of range (included).
* @param options - Assertion options.
*/
notWithin(start: number, finish: number, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` matches the regular expression.
*
* @param re - A regular expression that is expected to be matched.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
match(re: RegExp, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` matches the regular expression.
*
* @param re - A regular expression that is expected to be matched.
* @param options - Assertion options.
*/
match(re: RegExp, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` does not match the regular expression.
*
* @param re - A regular expression that is expected to be matched.
* @param message - An assertion message that will be displayed in the report if the test fails.
* @param options - Assertion options.
*/
notMatch(re: RegExp, message?: string, options?: AssertionOptions): TestControllerPromise;
/**
* Asserts that `actual` does not match the regular expression.
*
* @param re - A regular expression that is expected to be matched.
* @param options - Assertion options.
*/
notMatch(re: RegExp, options?: AssertionOptions): TestControllerPromise;
}
interface ClientFunctionOptions {
/**
* Contains functions, variables or objects used by the client function internally.
* Properties of the `dependencies` object will be added to the client function's scope as variables.
*/
dependencies?: {[key: string]: any};
/**
* If you need to call a client function from a Node.js callback, assign the current test controller to the `boundTestRun` option.
*/
boundTestRun?: TestController;
}
interface ClientFunction<R = any, A extends any[]= any[]> {
/**
* Client function
*
* @param args - Function arguments.
*/
(...args: A): Promise<R>;
/**
* Returns a new client function with a different set of options that includes options from the
* original function and new `options` that overwrite the original ones.
*
* @param options - New options.
*/
with(options: ClientFunctionOptions): ClientFunction<R, A>;
}
interface ClientFunctionFactory {
<R, A extends any[]>(fn: (...args: A) => R, options?: ClientFunctionOptions): ClientFunction<R, A>
}
interface ClientScriptCommon {
page?: any;
}
interface ClientScriptContent extends ClientScriptCommon {
content?: string;
}
interface ClientScriptModule extends ClientScriptCommon {
module?: string;
}
interface ClientScriptPath extends ClientScriptCommon {
path?: string;
}
type ClientScript = ClientScriptContent | ClientScriptModule | ClientScriptPath;
interface TextRectangle {
/**
* Y-coordinate, relative to the viewport origin, of the bottom of the rectangle box.
*/
bottom: number;
/**
* X-coordinate, relative to the viewport origin, of the left of the rectangle box.
*/
left: number;
/**
* X-coordinate, relative to the viewport origin, of the right of the rectangle box.
*/
right: number;
/**
* Y-coordinate, relative to the viewport origin, of the top of the rectangle box.
*/
top: number;
/**
* Width of the rectangle box (This is identical to `right` minus `left`).
*/
width: number;
/**
* Height of the rectangle box (This is identical to `bottom` minus `top`).
*/
height: number;
}
interface NodeSnapshot {
/**
* The number of child HTML elements.
*/
childElementCount: number;
/**
* The number of child nodes.
*/
childNodeCount: number;
/**
* `true` if this node has child HTML elements.
*/
hasChildElements: boolean;
/**
* `true` if this node has child nodes.
*/
hasChildNodes: boolean;
/**
* The type of the node.
* See https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
*/
nodeType: number;
/**
* The text content of the node and its descendants.
* See https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent
*/
textContent: string;
/**
* Attributes of the element.
*/
attributes?: {[name: string]: string};
/**
* The size of the element and its position relative to the viewport.
*/
boundingClientRect?: TextRectangle;
/**
* For checkbox and radio input elements, their current state. For other elements, `undefined`.
*/
checked?: boolean | undefined;
/**
* The list of element's classes.
*/
classNames?: string[];
/**
* The inner height of the element, including padding but not the horizontal scrollbar height, border, or margin.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientHeight
*/
clientHeight?: number;
/**
* The width of the left border of the element.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientLeft
*/
clientLeft?: number;
/**
* The width of the top border of the element.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientTop
*/
clientTop?: number;
/**
* The inner width of the element, including padding but not the vertical scrollbar width, border, or margin.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientWidth
*/
clientWidth?: number;
/**
* `true` if the element is focused.
*/
focused?: boolean;
/**
* The element's identifier.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/id
*/
id?: string;
/**
* The element's text content "as rendered".
* See https://html.spec.whatwg.org/multipage/dom.html#the-innertext-idl-attribute
*/
innerText?: string;
/**
* The namespace URI of the element. If the element does not have a namespace, this property is set to null.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/namespaceURI
*/
namespaceURI?: string | null;
/**
* The height of the element including vertical padding and borders.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetHeight
*/
offsetHeight?: number;
/**
* The number of pixels that the upper left corner of the element is offset by to the left within the `offsetParent` node.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetLeft
*/
offsetLeft?: number;
/**
* The number of pixels that the upper left corner of the element is offset by to the top within the offsetParent node.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetTop
*/
offsetTop?: number;
/**
* The width of the element including vertical padding and borders.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth
*/
offsetWidth?: number;
/**
* Indicates that `<option>` element is currently selected. For other elements, `undefined`.
*/
selected?: boolean | undefined;
/**
* For `<select>` element, the index of the first selected `<option>` element. For other elements, `undefined`.
*/
selectedIndex?: number | undefined;
/**
* The height of the element's content, including content not visible on the screen due to overflow.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollHeight
*/
scrollHeight?: number;
/**
* The number of pixels that the element's content is scrolled to the left.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollLeft
*/
scrollLeft?: number;
/**
* The number of pixels that the element's content is scrolled upward.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTop
*/
scrollTop?: number;
/**
* Either the width in pixels of the element's content or the width of the element itself, whichever is greater.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollWidth
*/
scrollWidth?: number;
/**
* The computed values of element's CSS properties.
*/
style?: {[prop: string]: string};
/**
* The name of the element.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/tagName
*/
tagName?: string;
/**
* For input elements, the current value in the control. For other elements, `undefined`.
*/
value?: string | undefined;
/**
* `true` if the element is visible.
*/
visible?: boolean;
/**
* `true` if the element has the specified class name.
*
* @param className - Name of the class.
*/
hasClass?(className: string): boolean;
/**
* Returns the computed value of the CSS property.
*
* @param propertyName - The name of the CSS property.
*/
getStyleProperty?(propertyName: string): string;
/**
* Returns the value of the attribute.
*
* @param attributeName - The name of the attribute.
*/
getAttribute?(attributeName: string): string | null;
/**
* Returns the value of the property from the `boundingClientRect` object.
*
* @param propertyName - The name of the property.
*/
getBoundingClientRectProperty?(propertyName: string): number;
/**
* `true` if the element has the attribute.
*
* @param attributeName - The name of the attribute.
*/
hasAttribute?(attributeName: string): boolean;
}
// Request Hook
//----------------------------------------------------------------------------------------------------------------------
interface RequestHook {
/**
* The `onRequest` method is called before sending the request.
*/
onRequest(requestEvent: object): Promise<void> | void;
/**
* The `onResponse` method is called after sending the request
*/
onResponse(responseEvent: object): Promise<void> | void;
}
interface RequestHookConstructor {
/**
* Creates a request hook
* @param requestFilterRules - determines which requests the hook handles
* @param responseEventConfigureOpts - defines whether to pass the response headers and body to the onResponse method
* @returns {RequestHook}
*/
new (requestFilterRules?: Array<any>, responseEventConfigureOpts?: object): RequestHook;
}
// Request Logger
//----------------------------------------------------------------------------------------------------------------------
interface RequestLoggerOptions {
/**
* Specifies whether the request headers should be logged.
*/
logRequestHeaders?: boolean;
/**
* Specifies whether the request body should be logged.
*/
logRequestBody?: boolean;
/**
* Specifies whether the request body should be stored as a String or a Buffer.
*/
stringifyRequestBody?: boolean;
/**
* Specifies whether the response headers should be logged.
*/
logResponseHeaders?: boolean;
/**
* Specifies whether the response body should be logged.
*/
logResponseBody?: boolean;
/**
* Specifies whether the response body should be stored as a string or a Buffer.
*/
stringifyResponseBody?: boolean;
}
interface LoggedRequest {
/**
* The user agent that sent the request.
*/
userAgent: string;
/**
* The request part of the logged request
*/
request: RequestData;
/**
* The response part of the logged request
*/
response: ResponseData;
}
interface RequestData {
/**
* The URL where the request is sent.
*/
url: string;
/**
* The request's HTTP method.
*/
method: string;
/**
* Request headers in the property-value form. Logged if the `logRequestHeaders` option is set to `true`.
*/
headers: Record<string, string>;
/**
* The request body. Logged if the `logRequestBody` option is set to `true`.
* A [Buffer](https://nodejs.org/api/buffer.html) or string depending on the `stringifyRequestBody` option.
*/
body: string | Buffer;
/**
* The timestamp that specifies when the request was intercepted.
*/
timestamp: number;
}
interface ResponseData {
/**
* The status code received in the response.
*/
statusCode: number;
/**
* Response headers in the property-value form. Logged if the `logResponseHeaders` option is set to `true`.
*/
headers: Record<string, string>;
/**
* The response body. Logged if the `logResponseBody` option is set to `true`.
* A [Buffer](https://nodejs.org/api/buffer.html) or string depending on the `stringifyResponseBody` option.
*/
body: string | Buffer;
/**
* The timestamp that specifies when the response was intercepted.
*/
timestamp: number;
}
interface RequestLogger extends RequestHook {
/**
* Returns whether the logger contains a request that matches the predicate.
* @param predicate - The predicate
*/
contains(predicate: (request: LoggedRequest) => boolean): Promise<boolean>;
/**
* Returns the number of requests that match the predicate.
* @param predicate - The predicate
*/
count(predicate: (request: LoggedRequest) => boolean): Promise<number>;
/**
* Clears all logged requests.
*/
clear(): void;
/**
* Returns an array of logged requests.
*/
requests: Array<LoggedRequest>;
}
interface RequestLoggerFactory {
(
filter?: string | RegExp | object | ((req: any) => boolean),
options?: RequestLoggerOptions
): RequestLogger;
}
// Request Mock
//----------------------------------------------------------------------------------------------------------------------
interface RequestMock {
/**
* Specifies requests to intercept
* @param filter - Specifies which requests should be mocked with a response that follows in the `respond` method.
*/
onRequestTo(filter: string | RegExp | object | ((req: RequestMockOptions) => boolean)): RequestMock;
/**
* Specifies the mocked response.
* @param body - The mocked response body.
* @param statusCode - The response status code.
* @param headers - Custom headers added to the response in the property-value form.
*/
respond(body?: object | string | ((req: RequestMockOptions, res: ResponseMock) => Promise<void> | void), statusCode?: number, headers?: Record<string, string>): RequestMock;
}
interface RequestMockFactory {
(): RequestMock;
}
/**
* {@link https://testcafe.io/documentation/402762/reference/test-api/requestmock/respond#requestoptions See documentation}.
*/
interface RequestMockOptions {
/** The request headers in the property-value form. */
headers: Record<string, string>;
/** The request body. */
body: Buffer;
/** The URL of the resource. */
url: string;
/** The protocol to use. Default: http:. */
protocol: string;
/** The alias for the host. */
hostname: string;
/** The domain name or IP address of the server to issue the request to. Default: localhost. */
host: string;
/** The port of the remote server. Default: 80. */
port: number;
/**
* The request path. Should include query string if any. E.G. '/index.html?page=12'. An exception
* is thrown when the request path contains illegal characters. Currently, only spaces are
* rejected but that may change in the future. Default: '/'.
*/
path: string;
/** The HTTP request method. Default: 'GET'. */
method: string;
/**
* Credentials that were used for authentication in the current session using NTLM or Basic
* authentication. For HTTP Basic authentication, these are `username` and `password`. NTLM
* authentication additionally specifies `workstation` and `domain`.
* See {@link https://testcafe.io/documentation/402845/guides/intermediate-guides/authentication?search#http-authentication HTTP Authentication}.
*/
credentials: Record<string, string>;
/**
* If a proxy is used, the property contains information about its `host`, `hostname`, `port`,
* `proxyAuth`, `authHeader` and `bypassRules`.
*/
proxy: Record<string, unknown>;
/**
* Specifies whether the request is an AJAX request (xhr or fetch).
*/
isAjax: Boolean;
}
interface ResponseMock {
headers: Record<string, string>;
statusCode: number;
setBody(value: string | object | Buffer | null): void;
}
// User Variables
//----------------------------------------------------------------------------------------------------------------------
interface UserVariables {
/**
* Custom property
*/
[key: string]: unknown;
}
interface Role {
}
interface RoleOptions {
/**
* Use this option to control which page is opened after you switch to the role.
*
* By default, TestCafe navigates back to the page that was opened previously to switching to the role.
* Set the `preserveUrl` option to true to save the URL to which the browser was redirected after logging in.
* TestCafe will navigate to the saved URL each time after you switch to this role.
*
* This option is useful if you store session-related data (like session ID) in the URL.
*/
preserveUrl?: boolean;
}
interface RoleFactory {
(url: String, fn: (t: TestController) => Promise<any>, options?: RoleOptions): Role;
/**
* Creates an anonymous user role.
*/
anonymous(): Role;
}
interface SelectorOptions {
/**
* If you need to call a selector from a Node.js callback, assign the current test
* controller to the `boundTestRun` option.
*/
boundTestRun?: TestController;
/**
* The amount of time, in milliseconds, allowed for an element returned by the
* selector to appear in the DOM before the test fails.
*/
timeout?: number;
/**
* Use this option to pass functions, variables or objects to selectors initialized with a function.
* The `dependencies` object's properties are added to the function's scope as variables.
*/
dependencies?: {[key: string]: any};
/**
* `true` to additionally require the returned element to become visible within `options.timeout`.
*/
visibilityCheck?: boolean;
}
interface SelectorAPI {
/**
* The number of child HTML elements.
*/
childElementCount: Promise<number>;
/**
* The number of child nodes.
*/
childNodeCount: Promise<number>;
/**
* `true` if this node has child HTML elements.
*/
hasChildElements: Promise<boolean>;
/**
* `true` if this node has child nodes.
*/
hasChildNodes: Promise<boolean>;
/**
* The type of the node.
* See https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
*/
nodeType: Promise<number>;
/**
* The text content of the node and its descendants.
* See https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent
*/
textContent: Promise<string>;
/**
* Attributes of the element.
*/
attributes: Promise<{[name: string]: string}>;
/**
* The size of the element and its position relative to the viewport.
*/
boundingClientRect: Promise<TextRectangle>;
/**
* For checkbox and radio input elements, their current state. For other elements, `undefined`.
*/
checked: Promise<boolean | undefined>;
/**
* The list of element's classes.
*/
classNames: Promise<string[]>;
/**
* The inner height of the element, including padding but not the horizontal scrollbar height, border, or margin.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientHeight
*/
clientHeight: Promise<number>;
/**
* The width of the left border of the element.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientLeft
*/
clientLeft: Promise<number>;
/**
* The width of the top border of the element.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientTop
*/
clientTop: Promise<number>;
/**
* The inner width of the element, including padding but not the vertical scrollbar width, border, or margin.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/clientWidth
*/
clientWidth: Promise<number>;
/**
* `true` if the element is focused.
*/
focused: Promise<boolean>;
/**
* The element's identifier.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/id
*/
id: Promise<string>;
/**
* The element's text content "as rendered".
* See https://html.spec.whatwg.org/multipage/dom.html#the-innertext-idl-attribute
*/
innerText: Promise<string>;
/**
* The namespace URI of the element. If the element does not have a namespace, this property is set to null.
* See https://developer.mozilla.org/en-US/docs/Web/API/Element/namespaceURI
*/
namespaceURI: Promise<string | null>;
/**
* The height of the element including vertical padding and borders.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetHeight
*/
offsetHeight: Promise<number>;
/**
* The number of pixels that the upper left corner of the element is offset by to the left within the `offsetParent` node.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetLeft
*/
offsetLeft: Promise<number>;
/**
* The number of pixels that the upper left corner of the element is offset by to the top within the offsetParent node.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetTop
*/
offsetTop: Promise<number>;
/**
* The width of the element including vertical padding and borders.
* See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth
*/
offsetWidth: Promise<number>;
/**
* Indicates that `<option>` element is currently selected. For other elements, `u