UI-licious Logo

UI-licious Cheatsheet

A quick reference guide to UI-licious commands for browser automation and testing.

Navigation and Page Info

Commands for navigating pages, refreshing, and asserting URLs and page titles.

Commands for navigating to URLs, refreshing the page, and going back/forward in browser history.

UI-licious will automatically wait for page to fully load before on page navigations (triggered by I.goTo, I.refreshPage, I.click, etc.)

I.goTo('https://example.com')

Navigate to a URL

I.goTo('/cart')

Navigate to a URL with relative path

I.goTo('https://example.com', { newTab: true })

Open a new tab and navigate to a URL

I.goTo("https://<username>:<password>@example.com")

Navigate to a URL with Basic Authentication

I.refreshPage()

Refresh the current page

UI.execute('window.history.back()')

Go back to the previous page

UI.execute('window.history.forward()')

Go forward to the next page

URL and Page Title

Commands for getting and asserting the current page URL and title.

let url = I.getUrl()

Get the current page URL

let title = I.getPageTitle()

Get the current page title

I.amAt('https://example.com')

Assert the current page URL with absolute URL

I.amAt('/cart')

Assert the current page URL with relative path

I.amAt('?search=keyword')

Assert the current page URL contains specific query parameters

I.amAt('#chapter-1')

Assert the current page URL contains specific hash

Page Elements

Commands for asserting element visibility, text, attributes, and counts.

Visibility

Assertion commands for checking if elements are visible or not on the page.

UI-licious checks for element visibility to human eyes, not just presence in the DOM. An element is considered visible if it has non-zero width and height, and is not hidden via CSS (e.g. display: none, visibility: hidden, opacity: 0, or positioned off-screen).

I.see('Login')

Assert that an element is visible on the page using smart targeting

I.see('button.login-btn')

Assert that an element is visible on the page using CSS selector

I.see('//button[@class="login-btn"]')

Assert that an element is visible on the page using XPath

I.dontSee('Logout')

Assert that an element is NOT visible on the page using smart targeting

I.dontSee('button.logout-btn')

Assert that an element is NOT visible on the page using CSS selector

I.dontSee('//button[@class="logout-btn"]')

Assert that an element is NOT visible on the page using XPath

Element Properties

Get or assert element properties such as text content, input values, CSS classes, attributes, and HTML content.

let text = I.getText("#username")

Get the text content of an element using CSS or XPATH

let value = I.getValue('Name')

Get the value of an input field using CSS or XPATH

UI.hasClass('button.submit-btn', 'active')

Assert that an element has a specific CSS class

UI.doesNotHaveClass('button.submit-btn', 'disabled')

Assert that an element does NOT have a specific CSS class

let href = UI.getAttribute('a.profile-link', 'href')

Get the value of a specific attribute of an element using CSS or XPATH

UI.hasAttribute('a.profile-link', 'href')

Assert that an element has a specific attribute

UI.hasAttribute('a.profile-link', 'href', 'https://example.com/user/john')

Assert that an element has a specific attribute with a specific value

UI.doesNotHaveAttribute('a.profile-link', 'target')

Assert that an element does NOT have a specific attribute

UI.doesNotHaveAttribute('a.profile-link', 'href', 'https://evil.com')

Assert that an element does NOT have a specific attribute with a specific value

let html = UI.getHTML('.article')

Get the outer HTML of an element using CSS or XPATH

let html = UI.getInnerHTML('.article')

Get the inner HTML of an element using CSS or XPATH

Element Count

Get or assert the count of elements matching a selector.

let count = I.getCount('.todo-item')

Get the count of elements matching a selector

I.count("table.results tr", 10)

Assert that a certain number of elements are present on the page

Mouse and Keyboard

Commands for mouse and keyboard interactions.

Click / Hover

Commands to click, double-click, right-click, and hover over elements.

UI-licious smart targeting locates elements by human-facing labels (e.g. labels, ARIA accessibility labels, text content, input field placeholders, nearby text) as well as tooltips (e.g. title, alt-text). It is case insensitive, and normalizes whitespaces and quotation marks.

I.click('Submit')

Click on an element with smart targeting (case insensitive)

I.click('button.submit-btn')

Click on an element with CSS selector

I.click('//button[@class="submit-btn"]')

Click on an element with XPath

I.click('Map', { offsetX: 10, offsetY: 20 })

Click on an element at a specific offset (x, y) from the top-left corner of the element

I.click(100, 200)

Click at a specific (x, y) coordinate on the viewport

I.doubleClick('Submit')

Double click on an element

I.rightClick('Image')

Right click on an element

I.hover('Menu')

Hover over an element

Drag and Drop

Commands for dragging and dropping elements.

I.dragTo("Do laundry", ".todo-list.completed")

Drag an element and drop it onto another element

I.dragBy(".slider-knob", 100, 0)

Drag an element by a deltaX and deltaY pixels

I.dragLeft(".slider-knob", 100)

Drag an element leftwards by a certain number of pixels

I.dragRight(".slider-knob", 100)

Drag an element rightwards by a certain number of pixels

I.dragUp("#draggable", 100)

Drag an element upwards by a certain number of pixels

I.dragDown("#draggable", 100)

Drag an element downwards by a certain number of pixels

Scroll

Commands for scrolling the page.

I.scrollBy(0, 500)

Scroll the page by a deltaX and deltaY pixels

I.scrollUp(500)

Scroll the page upwards by a certain number of pixels

I.scrollDown(500)

Scroll the page downwards by a certain number of pixels

I.scrollLeft(500)

Scroll the page leftwards by a certain number of pixels

I.scrollRight(500)

Scroll the page rightwards by a certain number of pixels

I.scrollTo(0, 1000)

Scroll to an (x, y) coordinate relative to the top-left of the page

I.scrollToTop()

Scroll to the top of the page

I.scrollToBottom()

Scroll to the bottom of the page (for infinite scrolling pages, this scrolls to the bottom of the currently loaded content)

Keyboard

Commands for keyboard interactions.

I.type('Hello, World!')

Type text into the focused element

I.press('Enter')

Press a key

I.press(['Control', 'A']) // Select All
I.press(['Meta', 'C']) // Copy (Cmd+C on Mac)
I.press(['Shift', 'Control', 'ArrowLeft']) // Select previous word

Press multiple keys with modifiers

I.pressEnter()

Press the Enter key

I.pressTab()

Press the Tab key

I.press('Escape')

Press the Escape key

I.press('Backspace')

Press the Backspace key

I.press('Delete')

Press the Delete key

I.pressUp()

Press the Arrow Up key

I.pressDown()

Press the Arrow Down key

I.pressLeft()

Press the Arrow Left key

I.pressRight()

Press the Arrow Right key

Forms

Commands for filling and clearing input fields, selecting checkboxes and radio buttons, selecting options in dropdowns, uploading files, and handling alert dialogs.

Text Input

Fill, clear, and assert text input fields.

UI-licious smart targeting locates input elements by human-facing labels (e.g. labels, ARIA accessibility labels, placeholder text, input value, nearby text) as well as input name attribute. It is case insensitive, and normalizes whitespaces and quotation marks.

I.fill('Username', 'myusername')

Locate an input field with smart targeting and fill it with text

I.fill('input#username', 'myusername')

Locate an input field using CSS selector and fill it with text

I.fill('//input[@id="username"]', 'myusername')

Locate an input field using XPath and fill it with text

I.filled('Username', 'myusername')

Assert that an input field has a specific value

I.clear('Username')

Clear the text in an input field located with smart targeting

Checkbox / Radio Button

Select, deselect, and assert checkboxes and radio buttons.

UI-licious smart targeting locates checkbox and radio button elements by human-facing labels (e.g. labels, ARIA accessibility labels, input value, nearby text) as well as the input name attribute. It is case insensitive, and normalizes whitespaces and quotation marks.

I.select('Remember me')

Check a checkbox or radio button located with smart targeting

I.select('input#remember-me')

Check a checkbox or radio button using CSS selector

I.select('//input[@id="remember-me"]')

Check a checkbox or radio button using XPath

I.selected('Remember me')

Assert that a checkbox or radio button is selected

I.deselect('Subscribe to newsletter')

Uncheck a checkbox located with smart targeting

I.deselect('input#subscribe-newsletter')

Uncheck a checkbox using CSS selector

I.deselect('//input[@id="subscribe-newsletter"]')

Uncheck a checkbox using XPath

I.deselected('Subscribe to newsletter')

Assert that a checkbox is NOT selected

Select Dropdown

Select and assert options in dropdowns.

UI-licious smart targeting locates select elements by human-facing labels (e.g. labels, ARIA accessibility labels, input value, nearby text) as well as the input name attribute. It is case insensitive, and normalizes whitespaces and quotation marks.

I.select('Country', 'United States')

Select an option in a dropdown located with smart targeting

I.select('select#country', 'United States')

Select an option in a dropdown using CSS selector

I.select('//select[@id="country"]', 'United States')

Select an option in a dropdown using XPath

I.selected('Country', 'United States')

Assert that a specific option is selected in a dropdown located with smart targeting

File Upload

Upload files to file input elements.

DO NOT click on the file input element to open the file dialog. Instead, use I.upload to directly set the file path to upload. 

I.upload('Profile Picture', '/path/to/file.jpg')

Upload a file to a file input located with smart targeting

I.upload('input#profile-picture', '/path/to/file.jpg')

Upload a file to a file input using CSS selector

I.upload('//input[@id="profile-picture"]', '/path/to/file.jpg')

Upload a file to a file input using XPath

I.upload('Profile Picture', UI.Downloads.files[0].path)

Upload a file that was downloaded during the test

Alerts

Handle alert, confirm, and prompt dialogs.

Alert / Confirm / Prompt dialogs must be accepted or dismissed when they appear before interacting with the page again.

I.seeAlert()

Assert that an alert / confirm / prompt dialog is open

I.seeAlert("Continue?")

Assert that an alert / confirm / prompt dialog is open with specific text

I.acceptAlert()

Accept an alert / confirm / prompt dialog

I.cancelAlert()

Dismiss an alert / confirm / prompt dialog

I.fillAlert('Jane')

Fill the prompt dialog with text

Targeting

Commands for improving element selection with smart targeting hints, and scoping interactions within iframes or specific DOM subtrees.

Hints for Smart Targeting

Provide hints to help the smart targeting engine locate related elements.

All I.see commands will automatically drop hints for the smart targeting engine to use for the next command. You can also manually drop hints using I.see.hint("text") which adds a higher weight to nearby elements when resolving the next command's target.

// Let's say we're on an employee listing page, and we want to click on "Edit" for the employee named "Janet".
I.see.hint("Janet")
I.click("Edit")

Drop a hint on a related element to help with smart targeting for the next command

Iframes and Subtrees

Scope interactions within iframes or specific DOM subtrees.

UI.context('iframe#secure-payment', () => {
  I.fill('Card Number', '4111 1111 1111 1111')
  I.fill('Expiry Date', '12/25')
  I.fill('CVC', '123')
});

Run commands within an iframe context

UI.context('.login-modal', () => {
  I.fill('Email', '[email protected]')
  I.fill('Password', 'password123')
});

Target elements within a specific subtree of the DOM

Storage

Commands for managing browser-side state such as cookies, local storage, and inspecting downloaded files.

Cookies

Set, assert, and delete browser cookies.

UI.COOKIE.set('session_id', 'abc123')

Set a cookie with name and value

UI.COOKIE.set({
    name: 'session_id',
    value: 'abc123',
    domain: 'example.com',
    path: '/',
    maxAge: 3600, // 1 hour
    secure: true,
    httpOnly: true,
  })

Set a cookie with options

UI.COOKIE.isSet('session_id')

Assert that a cookie with a specific name is set

UI.COOKIE.isEqual('session_id', 'abc123')

Assert that a cookie has a specific value

UI.COOKIE.delete('session_id')

Delete a cookie with a specific name

UI.COOKIE.deleteAll()

Delete all cookies available on the current page

Local Storage

Get, set, assert, and delete local storage items.

let value = UI.LocalStorage.get('cart')

Get a local storage item by key

UI.LocalStorage.set('theme', 'dark')

Set a local storage item by key and value

UI.LocalStorage.delete('cart')

Delete a local storage item by key

UI.LocalStorage.clear()

Delete all local storage items

Downloaded Files

Inspect and assert files downloaded during the test.

let files = UI.Downloads.files

Get a list of files downloaded during the test

UI.Downloads.hasFile('report.pdf')

Assert that a file is downloaded with a specific name

UI.Downloads.hasFile(/report-.*\.pdf/)

Assert that a file is downloaded matching a specific name pattern

TEST.assert(
    UI.Downloads.files[0].size >= 1, 
    'File must be at least 1 byte'
  )

Assert that a downloaded file has a minimum size in bytes

Test Data

Commands for injecting dynamic test data from Datasets or loading test data from external files (e.g. JSON or CSV files).

Datasets

Use variables and secrets from configured Datasets in your tests.

// navigate to a URL from the DATA set, 
// or default to example.com
I.goTo(DATA.url || 'https://example.com')

// fill username and password from the DATA set
I.fill('Username', DATA.username)
I.fill('Password', DATA.password)

I.click('Login')

Use variables and secrets from Dataset.

Load from File

Load test data from external files (e.g. JSON or CSV files).

let users = TEST.loadDataFromJson('data/users.json')

Load test data from a JSON file

let users = TEST.loadDataFromCsv('data/users.csv', { header: "row" })

Load test data from a CSV file with first row as header

let products = TEST.loadDataFromCsv('data/products.csv', { header: "col" })

Load test data from a CSV file with first column as header

Window Management

Commands for controlling browser tabs, switching between them, closing tabs, and resizing the browser window or viewport.

Switch / Close Tabs

Open, switch between, and close browser tabs.

UI-licious will automatically switch to newly opened tabs when detected (e.g. when <a target="_blank"> link is clicked)

I.goTo('https://example.com', { newTab: true })

Open a new tab and navigate to a URL

I.switchTab()

Switch to the next tab (cycles back to the first tab if on the last tab)

I.switchTab('Wikipedia')

Switch to a specific tab by title

I.switchTab(1)

Switch to a specific tab by index (1-based)

I.closeTab()

Close the current tab

Window / Viewport Size

Get and set the browser window and viewport size.

UI.resize(1280, 800)

Set the browser window size (includes browser UI like address bar)

UI.resize(1280, 800, { target: true })

Set the browser viewport size (excludes browser UI like address bar)

let width = UI.outerWidth

Get the current browser window width

let height = UI.outerHeight

Get the current browser window height

let width = UI.innerWidth

Get the current browser viewport width

let height = UI.innerHeight

Get the current browser viewport height

Test Flow Control

Commands for controlling the flow of your test, including conditional flows, waits, running other tests, and stopping the test early.

Conditional Flows

Run commands conditionally using if statements with I.see$ or other assertions.

if (I.see$("We use cookies")) {
  I.click("Accept Cookies");
}
I.click("Log In");

Run commands conditionally using if with I.see$

Waits and Command Timeouts

Set explicit waits and configure command timeouts.

Interaction commands (e.g. I.click, I.fill, I.select, I.upload) automatically wait for elements to be visible (to humans) before attempting interaction.

Assertion commands (e.g. I.see, I.amAt, etc) will automatically retry until the assertion passes or timeout is reached.

The default command timeout is 15 seconds, which can be changed using TEST.setCommandTimeout(seconds);.

Use explicit waits only when necessary.

I.wait(30) // wait for 30 seconds

Wait for a specific number of seconds

I.click("Confirm Transaction")

// set command timeout to 10 minutes
TEST.setCommandTimeout(10 * 60); 
I.see("Transaction Completed")

// reset command timeout back to 15 seconds
TEST.setCommandTimeout(15);

Set timeout for all commands in the test

Run Another Test

Run another test script from within the current test.

TEST.run('auth/login')

Run another test script using absolute path

TEST.run('./loginAsAdmin')

Run another test script using relative path

Stop Test

Stop the test execution early.

TEST.stop();

Stop test immediately

if(I.see$("500 Internal Server Error")){
  TEST.log.info("Server error detected, stopping test.");
  TEST.stop();
}

Stop test when a condition is met

Advanced Scripting

Advanced commands for executing custom JavaScript in the page context and making HTTP requests from the browser context.

Execute JavaScript in the Page Context

Execute custom JavaScript code in the context of the page to interact with the DOM or retrieve information.

UI.execute('alert("Hello!");')

Execute Javascript in the context of the page using a string

let ua = UI.execute(() => {
  return navigator.userAgent;
});

Execute Javascript in the context of the page using a function

let sum = UI.execute((a, b) => {
  return a + b;
}, [5, 10]);

Execute Javascript in the context of the page with arguments

HTTP Requests

Make HTTP requests (GET, POST, PUT, DELETE, etc.) from the browser context.

These commands make HTTP requests from the browser context, so they are subject to CORS restrictions.

These commands are useful for retrieving test data from a remote server or setting up test state via APIs. We do not recommend using these commands for the purpose of API testing — please use a dedicated API testing tool instead.

let response = UI.httpGet('https://api.example.com/listPets');

Make a GET request to a URL

let response = UI.httpGet('https://api.example.com/listPets', {
  params: {
    page: 1,
    limit: 10
  }
});
let pets = response.data;

Make a GET request to a URL

let payload = { name: 'John', age: 30 };
let response = UI.httpPost('https://api.example.com/addPet', {
  data: {
    name: 'Fido',
    type: 'Dog'
  }
});
let newPet = response.data;

Make a POST request to a URL with JSON payload

let response = UI.httpRequest('https://api.example.com/updatePet/123', {
  method: 'PUT',
  withCredentials: true,
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  data: {
    name: 'Fido',
    type: 'Dog',
    age: 5
  }
});
let updatedPet = response.data;

Make a HTTP request with custom method, headers, and payload

Test Outputs

Commands for capturing screenshots and printing custom log messages to the test report.

Screenshots

Manually take screenshots and control automatic screenshot capturing.

UI-licious automatically captures screenshots for every test command. It's not necessary to manually take screenshots unless you have set TEST.autoScreenshots = false; in your test script.

I.takeScreenshot()

Take a screenshot of the viewport

TEST.autoScreenshots = false;
I.click("Show Password");

Disable automatic screenshots for the rest of the test

I.click("Hide Password")
TEST.autoScreenshots = true;

Re-enable automatic screenshots for the rest of the test

Logging

Log custom messages to the test report, assert conditions, and control logging behavior.

TEST.log.info("Filling out login form")

Log a message to the test report

TEST.log.pass("Logged in as guest user")

Log a message to the test report with passing status

TEST.log.fail("Login failed")

Log a message to the test report with failure status

let resultCount = I.getCount('.search-results .result-item');
TEST.assert(resultCount > 0, "Search should return at least 1 result");

Assert a condition is true, otherwise fail the test with a message

// if button is not found, log without failing the test
I.click$("Accept Cookies");

Suppress errors for a command using $ postfix

I.click$$("Reveal Secret")

Hide logs for a command using $$ postfix

Frequently Asked Questions

  • What language does UI-licious run on?

  • Can I write custom functions?

  • Does UI-licious commands execute synchronously or asynchronously?

  • How does UI-licious smart targeting work?