Version: 1.5

Browser

Browser is the main entry point in each step, it's your direct connection to the browser running the test.

If you're coming from Selenium, the browser is synonymous with the Driver interface in Selenium.

If you're coming from Puppeteer, think of the Browser as a wrapper around the Puppeteer Page object.

You don't need to create a browser instance because it is passed into each step for your, and reset after each test loop.

my-test.perf.ts
import { step } from "@flood/element";
export default () => {
step("Start", async (browser) => {
await browser.visit("https://challenge.flood.io");
});
};

Methods

authenticate([, username, password])

Sets the HTTP Authentication details to use if the page is presented with an authentication prompt.

Call without any args to disable authentication.

Parameters

  • username? string (Optional)
  • password? string (Optional)
  • returns: Promise<void>

blur(locator)

Removes focus from the specified DOM element.

Parameters

clear(locatable)

Clears the selected value of an input or select control.

Parameters

clearBrowserCache()

Clear browser cache.

Parameters

clearBrowserCookies()

Clear browser cookies.

Parameters

click(locatable[, options])

Sends a click event to the element located at selector. If the element is currently outside the viewport it will first scroll to that element.

Example:

my-test.perf.ts
step("Start", async (browser) => {
await browser.click(By.partialLinkText("Start"));
});

In this example we're constructing a Locatable using the By.partialLinkText() Locator, which will match the first <a> tag which contains the text "Start".

Parameters

doubleClick(locatable[, options])

Sends a double-click event to the element located by the supplied Locator or selector. If the element is currently outside the viewport it will first scroll to that element.

Parameters

emulateDevice(deviceName)

Configure Browser to emulate a given device

Parameters

evaluate(fn, ...args)

Parameters

  • fn <function|string> Function to be evaluated in the page context
  • args any[]
  • returns: Promise<any>

findElement(locator)

Uses the provided locator to find the first element it matches, returning an ElementHandle. If no element is found throws an error.

Parameters

findElements(locator)

Uses the provided locator to find all elements matching the locator condition, returning an array of ElementHandles

Parameters

focus(locator)

Makes the element located by the first argument the receiver of future input.

Parameters

highlightElement(element)

Highlight an element. Useful in concert with takeScreenshot to tweak your locators.

Parameters

maybeFindElement(locator)

Uses the provided locator to find the first element it matches, returning an ElementHandle.

Parameters

press(keyCode[, options])

Presses a key on the keyboard specified by key code. For example, [Key.ALT][key.alt]

Parameters

scrollBy(x, y[, options])

Scroll the document by the given number of pixels.

Parameters

  • x number How many pixels to scroll by, along the x-axis (horizontal). Positive values will scroll to the right, while negative values will scroll to the left.

  • y number How many pixels to scroll by, along the y-axis (vertical). Positive values will scroll down, while negative values scroll up.

  • x and y can take 'window.innerHeight' and 'window.innerWidth' as special values

  • options is an object containing ScrollOptions.

scrollTo(position[, options])

Scroll the document to the specified position.

Parameters

  • position can be any of these types:

    • ElementHandle
    • Locator
    • Point: an array of x(number) and y(number) co-ordinate
    • String: 'top', 'bottom', 'left' or 'right'

  • options is an object containing ScrollOptions.

selectByIndex(locatable, index)

Selects an option within a <select> tag by its index in the list.

Parameters

selectByText(locatable, text)

Selects an option within a <select> tag by matching its visible text.

Parameters

selectByValue(locatable, ...values)

Selects an option within a <select> tag using the value of the <option> element.

Parameters

sendKeys(...keys)

sendKeys simulates typing a list of strings on the keyboard.

If a string is a member of Key it is pressed individually. Otherwise the string is typed. This allows sendKeys to simulate a user typing control keys such as Key.ENTER.

Example:

my-test.perf.ts
await browser.click("#input_address");
await browser.sendKeys("Hello, World!", Key.ENTER);

Parameters

sendKeyCombinations(...keys)

This will simulate the act of pressing a combination of keys on the keyboard at the same time. Use commas to separate individual keys.

SOME COMBINATIONS MAY NOT WORK ON MACOS

On MacOS, some combinations are emulated by the Operating System, instead of the browser. Therefore, you may find some combinations not working as expected, like Command + A (select all), Command + C (copy), Command + V (paste), etc. More information can be found here

Example:

my-test.perf.ts
await browser.sendKeyCombinations(Key.SHIFT, 'KeyA');

setUserAgent(userAgent)

Set Browser to send a custom User Agent (UA) string

Parameters

switchTo()

Switch the focus of the browser to another frame, tab, or window.

Parameters

takeScreenshot([, options])

Takes a screenshot of the whole page and saves it to the flood/results folder with a random sequential name. You can download the archive of your test results at the end of the test to retrieve these screenshots.

Parameters

title()

Returns the title of the current page

Parameters

type(locatable, text[, options])

Types a string into an <input> control, key press by key press. Use this to fill inputs as though it was typed by the user.

Example:

my-test.perf.ts
step("Step 1", async (browser) => {
await browser.type(By.css("#email"), "user@example.com");
});

Parameters

visit(url[, options])

Instructs the browser to navigate to a specific page. This is typically used as the entrypoint to your test, as the first instruction it is also responsible for creating a new Browser tab for this page to load into.

Example:

my-test.perf.ts
step("Start", async (browser) => {
await browser.visit("https://example.com");
});

Parameters

wait(timeoutOrCondition)

Creates a waiter which will pause the test until a condition is met or a timeout is reached. This can be used for validation or control flow.

Check out Until for a rich set of wait Conditions.

Example:

my-test.perf.ts
step("Start", async (browser) => {
await browser.wait(Until.elementIsVisible(By.css("h1.title")));
});

You can use either a numeric value in seconds to wait for a specific time, or a Condition, for more flexible conditions.

Parameters

waitForNavigation()

Parameters

Locatable

Locatable represents anything able to be located, either a string selector or a <Locator>. <Locator>s are generally created using <By> methods.

[Locator] | [ElementHandle] | string

NullableLocatable

NullableLocatable represents a <Locatable> which could also be null.

Note that most Element location API methods accept a NullableLocatable but will throw an <Error> if its actually <null>.

[Locatable] | null

NavigationOptions

An object which might have the following properties

Properties

  • timeout <number> (Optional) Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout.
  • waitUntil <string | array> (Optional) When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
    • "load" - consider navigation to be finished when the load event is fired.
    • "domcontentloaded" - consider navigation to be finished when the DOMContentLoaded event is fired.
    • "networkidle0" - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
    • "networkidle2" - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

ScreenshotOptions

Defines the screenshot options.

Properties

  • clip <Object> (Optional) An object which specifies clipping region of the page. Should have the following fields:
    • x <number> The x-coordinate of top-left corner of clipping area.
    • y <number> The y-coordinate of top-left corner of clipping area.
    • height <number> The height of clipping area.
    • width <number> The width of clipping area.
  • encoding <string> (Optional) The encoding of the image, can be either "base64" or "binary". Defaults to binary.
  • fullPage <boolean> (Optional) When true, takes a screenshot of the full scrollable page. Defaults to false.
  • omitBackground <boolean> (Optional) Hides default white background and allows capturing screenshots with transparency. Defaults to false.
  • path <string> (Optional) The file path to save the image to. The screenshot type will be inferred from file extension.
    If path is a relative path, then it is resolved relative to current working directory.
    If no path is provided, the image won't be saved to the disk.
  • quality <number> (Optional) The quality of the image, between 0-100. Not applicable to png images.
  • type <string> (Optional) Specify screenshot type, can be either "jpeg" or "png". Defaults to png.

ScrollOptions

Is an Object with the following properties:

  • behaviour: Defines the transition animation. One of 'auto' (default) or 'smooth'.
  • block: Defines vertical alignment. One of 'start' (default), 'center', 'end', or 'nearest'.
  • inline: Defines horizental alignment. One of 'start', 'center', 'end', or 'nearest' (default).

Note:

  1. If you use behaviour: 'smooth', it may take the browser some time to scroll. Therefore, consider adding a wait after the scroll action to avoid unexpected error.
  2. block and inline only work with browser.scrollTo(), with ElementHandle or Locator as the 1st parameter.
Edit this page