projecte_ionic/node_modules/@stencil/core/testing/puppeteer/puppeteer-declarations.d.ts
2022-02-09 18:30:03 +01:00

430 lines
18 KiB
TypeScript
Executable file
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/// <reference types="node" />
import type { EventInitDict, EventSpy, ScreenshotDiff, ScreenshotOptions } from '@stencil/core/internal';
import type { ClickOptions, HTTPResponse as PuppeteerHTTPResponse, Page, ScreenshotOptions as PuppeteerScreenshotOptions, WaitForOptions } from 'puppeteer';
/**
* This type helps with declaration merging as a part of Stencil's migration from Puppeteer v5.4.3 to v10.0.0. In
* v5.4.3, `HttpResponse` was an interface whereas v10.0.0 declares it as a class. It is redeclared here to help teams
* migrate to a newer minor version of Stencil without requiring a Puppeteer upgrade/major version of Stencil. This type
* should be removed as a part of the Stencil 3.0 release.
*/
export declare type HTTPResponse = PuppeteerHTTPResponse;
/**
* These types help with declaration merging as a part of Stencil's migration from Puppeteer v5.4.3 to v10.0.0. In
* v10.0.0, `WaitForOptions` is a renamed version of `NavigationOptions` from v5.4.3, who has had its type hierarchy
* flattened.
*
* See {@link https://github.com/DefinitelyTyped/DefinitelyTyped/blob/8290e943f6b398acf39ee1b2e486824144e15bc8/types/puppeteer/index.d.ts#L605-L622}
* for the v5.4.3 types.
*
* These types are redeclared here to help teams migrate to a newer minor version of Stencil without requiring a
* Puppeteer upgrade/major version of Stencil. These type additions should be removed as a part of the Stencil 3.0
* release.
*/
declare module 'puppeteer' {
type LifeCycleEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
interface WaitForOptions {
timeout?: number;
waitUntil?: LifeCycleEvent | LifeCycleEvent[];
}
}
/**
* This type was once exported by Puppeteer, but has since moved to an object literal in (Puppeteers) native types.
* Re-create it here as a named type to use across multiple Stencil-related testing files.
*/
export declare type PageCloseOptions = {
runBeforeUnload?: boolean;
};
export interface NewE2EPageOptions extends WaitForOptions {
url?: string;
html?: string;
failOnConsoleError?: boolean;
failOnNetworkError?: boolean;
}
declare type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
declare type PuppeteerPage = Omit<Page, 'bringToFront' | 'browser' | 'screenshot' | 'emulate' | 'emulateMedia' | 'frames' | 'goBack' | 'goForward' | 'isClosed' | 'mainFrame' | 'pdf' | 'reload' | 'target' | 'title' | 'viewport' | 'waitForNavigation' | 'screenshot' | 'workers' | 'addListener' | 'prependListener' | 'prependOnceListener' | 'removeAllListeners' | 'setMaxListeners' | 'getMaxListeners' | 'listeners' | 'rawListeners' | 'emit' | 'eventNames' | 'listenerCount' | '$x' | 'waitForXPath'>;
export interface PageDiagnostic {
type: 'error' | 'pageerror' | 'requestfailed';
message?: string;
location?: string;
}
/**
* The E2EPage is a wrapper utility to Puppeteer in order to
* to create easier to write and read end-to-end tests.
*/
export interface E2EPage extends PuppeteerPage {
/**
* `Experimental`
* Takes a screenshot of the page, then compares the current screenshot
* against the master screenshot. The returned screenshot compare
* results can then be used to test pixel mismatches, such as
* `expect(results).toMatchScreenshot()`.
*/
compareScreenshot(): Promise<ScreenshotDiff>;
/**
* `Experimental`
* Takes a screenshot of the page, then compares the current screenshot
* against the master screenshot. The provided `description` will be
* added onto its current description, which comes from the test description.
*/
compareScreenshot(description: string): Promise<ScreenshotDiff>;
/**
* `Experimental`
* Takes a screenshot of the page, then compares the current screenshot
* against the master screenshot. The `opts` argument can be used to
* customize screenshot options.
*/
compareScreenshot(opts: ScreenshotOptions): Promise<ScreenshotDiff>;
/**
* `Experimental`
* Takes a screenshot of the page, then compares the current screenshot
* against the master screenshot. The `description` argument will be
* added onto its current description, which comes from the test description.
* The `opts` argument can be used to customize screenshot options.
*/
compareScreenshot(description: string, opts: ScreenshotOptions): Promise<ScreenshotDiff>;
/**
* Sets a debugger;
*/
debugger(): Promise<void>;
/**
* Find an element that matches the selector, which is the same as
* `document.querySelector(selector)`. Use `>>>` within the
* selector to find an element within the host element's shadow root.
* For example, to select the first `div` inside of the component
* `my-cmp`, the call would be `page.find('my-cmp >>> div')`.
* Returns `null` if an element was not found.
*/
find(selector: FindSelector): Promise<E2EElement>;
/**
* Find all elements that match the selector, which is the same as
* `document.querySelectorAll(selector)`. Use `>>>` within the
* selector to find elements within the host element's shadow root.
* For example, to select all of the `li` elements inside of the component
* `my-cmp`, the call would be `page.findAll('my-cmp >>> li')`.
* Returns an empty array if no elements were found.
*/
findAll(selector: string): Promise<E2EElement[]>;
/**
* During an end-to-end test, a dev-server is started so `page.goto(url)` can be used
* on the app being tested. Urls are always relative since the dev server provides
* a localhost address. A shortcut to `page.goto(url)` is to set the `url` option
* when creating a new page, such as `const page = await newE2EPage({ url })`.
*/
goTo(url: string, options?: WaitForOptions): Promise<HTTPResponse | null>;
/**
* Instead of testing a url directly, html content can be mocked using
* `page.setContent(html)`. A shortcut to `page.setContent(html)` is to set
* the `html` option when creating a new page, such as
* `const page = await newE2EPage({ html })`.
*/
setContent(html: string, options?: WaitForOptions): Promise<void>;
/**
* Used to test if an event was, or was not dispatched. This method
* returns a promise, that resolves with an EventSpy. The EventSpy
* can be used along with `expect(spy).toHaveReceivedEvent()`,
* `expect(spy).toHaveReceivedEventTimes(x)` and
* `expect(spy).toHaveReceivedEventDetail({...})`.
*/
spyOnEvent(eventName: string, selector?: 'window' | 'document'): Promise<EventSpy>;
/**
* Both Stencil and Puppeteer have an asynchronous architecture, which is a good thing
* for performance. Since all calls are async, it's required that
* `await page.waitForChanges()` is called when changes are made to components.
* An error will be thrown if changes were made to a component but `waitForChanges()`
* was not called.
*/
waitForChanges(): Promise<void>;
/**
* Waits for the event to be received on `window`. The optional second argument
* allows the listener to be set to `document` if needed.
*/
waitForEvent(eventName: string): Promise<any>;
getDiagnostics(): PageDiagnostic[];
}
export interface E2EPageInternal extends E2EPage {
isClosed(): boolean;
_e2eElements: E2EElementInternal[];
_e2eEvents: Map<number, WaitForEvent>;
_e2eEventIds: number;
_e2eGoto(url: string, options?: Partial<WaitForOptions>): Promise<HTTPResponse | null>;
_e2eClose(options?: PageCloseOptions): Promise<void>;
screenshot(options?: PuppeteerScreenshotOptions): Promise<Buffer>;
}
export interface E2EElement {
/**
* Used to call a method on a component. For example, if a component
* has the method `cmp.myMethod(arg1, arg2)`, calling this method
* from a e2e test could be `cmp.callMethod('myMethod', arg1, arg2)`.
*/
callMethod(methodName: string, ...methodArgs: any[]): Promise<any>;
/**
* Gets and sets the value of the class attribute of the e2e element.
* Note that `await page.waitForChanges()` must be called before reading
* the value if content has changed.
*/
className: string;
/**
* Using classList is a convenient alternative to accessing an element's list
* of classes as a space-delimited string via `element.className`.
*/
classList: {
/**
* Add specified class values. If these classes already exist in
* attribute of the element, then they are ignored.
*/
add: (...tokens: string[]) => void;
/**
* Remove specified class values. Note: Removing a class that does
* not exist does NOT throw an error.
*/
remove: (...tokens: string[]) => void;
/**
* If class exists then remove it, if not, then add it.
*/
toggle: (token: string) => void;
/**
* Checks if specified class value exists in class attribute of the element.
*/
contains: (className: string) => boolean;
};
/**
* Calling `click()` on an element scrolls it into view if needed, and
* then uses `page.mouse` to click in the center of the element.
* Please see the puppeteer docs for more information.
*/
click(options?: ClickOptions): Promise<void>;
/**
* Find a child element that matches the selector, which is the same as
* `element.querySelector(selector)`. Use `>>>` within the
* selector to find an element within a host element's shadow root.
* For example, to select the first `div` inside of the component
* `my-cmp`, which is a child of this element, the call would be
* `element.find('my-cmp >>> div')`. Returns `null` if no
* elements were found.
*/
find(selector: FindSelector): Promise<E2EElement>;
/**
* Find all child elements that match the selector, which is the same as
* `element.querySelectorAll(selector)`. Use `>>>` within the
* selector to find elements within a host element's shadow root.
* For example, to select all `li` elements inside of the component
* `my-cmp`, which is a child of this element, the call would be
* `element.findAll('my-cmp >>> li')`. Returns an empty array if
* no elements were found.
*/
findAll(selector: FindSelector): Promise<E2EElement[]>;
/**
* Sets focus on the element.
*/
focus(): Promise<void>;
/**
* Returns the value of a specified attribute on the element. If the
* given attribute does not exist, the value returned will be null.
*/
getAttribute(name: string): string;
/**
* Used to get a property set on a component. For example, if a
* component has the property `elm.myProp`, then calling
* `elm.getProperty('myProp')` would return the `myProp` property value.
*/
getProperty(propertyName: string): Promise<any>;
/**
* Returns an object that reports the values of all CSS properties of this
* element after applying active stylesheets and resolving any basic computation
* those values may contain. Individual CSS property values are accessed by
* simply indexing with CSS property names. The method is shortcut and an async
* version of using `window.getComputedStyle(element)` directly.
*/
getComputedStyle(pseudoElt?: string | null): Promise<CSSStyleDeclaration>;
/**
* Sets hover on the element.
*/
hover(): Promise<void>;
/**
* Gets and sets `id` property of the element.
* Note that `await page.waitForChanges()` must be called before reading
* the value if content has changed.
*/
id: string;
/**
* Gets and sets `innerHTML` property of the element.
* Note that `await page.waitForChanges()` must be called before reading
* the value if content has changed.
*/
innerHTML: string;
/**
* Gets and sets `innerText` property of the element.
* Note that `await page.waitForChanges()` must be called before reading
* the value if content has changed.
*/
innerText: string;
/**
* Resolves to true if the element is visible in the current viewport.
*/
isIntersectingViewport(): Promise<boolean>;
/**
* Resolves `true` when the element's style is `display !== 'none'`,
* `visibility !== 'hidden'` and `opacity !== '0'`.
*/
isVisible(): Promise<boolean>;
/**
* Node name of the node, which in an element's case is the tag name.
* Note, this will always be upper-cased.
*/
nodeName: string;
/**
* The type of a node represented by a number.
* Element = 1, TextNode = 3, Comment = 8,
* Document Fragment (also what a shadow root is) = 11.
*/
nodeType: number;
/**
* Gets the element's `outerHTML. This is a read-only property and will
* throw an error if set.
*/
outerHTML: string;
/**
* Focuses the element, and then uses `keyboard.down` and `keyboard.up`.
* If key is a single character and no modifier keys besides Shift are
* being held down, a keypress/input event will also be generated. The
* text option can be specified to force an input event to be generated.
* Note: Modifier keys DO effect `elementHandle.press`. Holding down Shift
* will type the text in upper case.
* Key names: https://github.com/puppeteer/puppeteer/blob/main/src/common/USKeyboardLayout.ts
*/
press(key: string, options?: {
text?: string;
delay?: number;
}): Promise<void>;
/**
* Removes the attribute on the specified element. Note that
* `await page.waitForChanges()` must be called before reading
* the value if content has changed.
*/
removeAttribute(name: string): void;
/**
* Sets the value of an attribute on the specified element. If the
* attribute already exists, the value is updated; otherwise a new
* attribute is added with the specified name and value. The value
* will always be converted to a string. Note that
* `await page.waitForChanges()` must be called before reading
* the value if content has changed.
*/
setAttribute(name: string, value: any): void;
/**
* Used to set a property set on a component. For example, if a
* component has the property `elm.myProp`, then calling
* `elm.setProperty('myProp', 88)` would set the value `88` to
* the `myProp` property on the component.
*/
setProperty(propertyName: string, value: any): void;
/**
* The ShadowRoot interface of the Shadow DOM API is the root node of a
* DOM subtree that is rendered separately from a document's main DOM tree.
* This value will be `null` if the element does not have a `shadowRoot`.
*/
shadowRoot: ShadowRoot;
/**
* Used to test if an event was, or was not dispatched. This method
* returns a promise, that resolves with an EventSpy. The EventSpy
* can be used along with `expect(spy).toHaveReceivedEvent()`,
* `expect(spy).toHaveReceivedEventTimes(x)` and
* `expect(spy).toHaveReceivedEventDetail({...})`.
*/
spyOnEvent(eventName: string): Promise<EventSpy>;
/**
* Represents the tab order of the current element. Setting the
* `tabIndex` property will also set the `tabindex` attribute.
*/
tabIndex: number;
/**
* Tag name of the element. Note, this will always be upper-cased.
*/
tagName: string;
/**
* This method scrolls the element it into view if needed,
* and then uses `page.touchscreen` to tap in the center of the element.
*/
tap(): Promise<void>;
/**
* The `textContent` property represents the text content of a node
* and its descendants. Note that `await page.waitForChanges()` must
* be called before reading the value if content has changed.
*/
textContent: string;
/**
* Represents the `title` of the element, the text usually displayed in a
* 'tool tip' popup when the mouse is over the displayed node.
*/
title: string;
/**
* Toggles a `boolean` attribute (removing it if it is present and adding
* it if it is not present) on the given element. Note that
* `await page.waitForChanges()` must be called before reading
* the value if content has changed. The optional `force` argument is a
* `boolean` value to determine whether the attribute should be added or
* removed, no matter whether the attribute is present or not at the moment.
*/
toggleAttribute(name: string, force?: boolean): void;
/**
* This is a convenience method to easily create a `CustomEvent`,
* and dispatch it from the element, to include any custom event
* `detail` data as the second argument.
*/
triggerEvent(eventName: string, eventInitDict?: EventInitDict): void;
/**
* Sends a keydown, keypress/input, and keyup event for each character in the text.
* To press a special key, like Control or ArrowDown, use `keyboard.press`.
*/
type(text: string, options?: {
delay: number;
}): Promise<void>;
/**
* Waits until the element's style is `display !== 'none'`,
* `visibility !== 'hidden'`, `opacity !== '0'` and the element
* is connected to the document.
*/
waitForVisible(): Promise<void>;
/**
* Waits until the element's style is `display === 'none'`, or
* `visibility === 'hidden'`, or `opacity === '0'`, or the element
* is no longer connected to the document.
*/
waitForNotVisible(): Promise<void>;
/**
* Waits until the given event is listened in the element.
*/
waitForEvent(eventName: string): Promise<any>;
}
export interface E2EElementInternal extends E2EElement {
e2eDispose(): Promise<void>;
e2eRunActions(): Promise<unknown>;
e2eSync(): Promise<void>;
}
export declare type FindSelector = string | FindSelectorOptions;
export interface FindSelectorOptions {
/**
* Finds an element with text content matching this
* exact value after the whitespace has been trimmed.
*/
text?: string;
/**
* Finds an element with text content containing this value.
*/
contains?: string;
}
export interface WaitForEventOptions {
timeout?: number;
}
export interface WaitForEvent {
eventName: string;
callback: (ev: any) => void;
}
export interface BrowserWindow extends Window {
stencilOnEvent(id: number, event: any): void;
stencilSerializeEvent(ev: CustomEvent): any;
stencilSerializeEventTarget(target: any): any;
stencilAppLoaded: boolean;
}
export {};