UI-licious Documentation

Appearance

Clicking Around ​

Clicking is one of the most common interactions on a webpage.

To click on an element, use the I.click() command.

There are several ways to target an element or a point to click on:

  • by visible text
  • by CSS or XPath selector
  • by offset

Clicking based on visible text ​

In most cases, you should target an element using the visible text on the page. For example:

js
I.click("Login")

UI-licious locates the element that best matches the text, taking into account:

  • the visible text content of the element
  • associated <label> elements
  • descriptive attributes such as aria-label, title and alt-text
  • nearby or adjacent text

We strongly recommend targeting elements using visible text over CSS or XPath selectors. Tests written this way are more readable and more tolerant to changes in the underlying HTML structure.

Clicking on icon buttons and images ​

Sometimes, buttons or controls do not have visible text, but instead may expose their purpose through tooltips or accessibility attributes.

UI-licious can locate elements using descriptive attributes such as aria-label and title.

For example, a "Zoom In" button with a "plus" icon:

html
<button title="Zoom In">
	<img src="/assets/images/plus-icon.svg" width="16" height="16"/>
</button>

can be targeted using:

js
I.click("Zoom In")

Clicking using CSS or XPath selectors ​

In some cases, it may be necessary to use CSS or XPath selectors, such as when:

  • the element has no visible text or descriptive attributes
  • there are multiple elements with the same label

You can use I.click() with CSS or XPath selectors:

js
// using CSS
I.click("#zoom-in-btn")

// using XPath
I.click("//[@data-test-id='close-button']")

Unless your team has established a clear strategy for locating elements using data-test-id attributes, selectors should be used sparingly, as they tend to break more easily.

TIP

Prefer clicking by visible text whenever possible. It produces tests that are easier to read and more resilient to UI changes.

Clicking using offsets ​

In advanced scenarios, you may need to click on a specific position rather than a specific element, for example:

  • clicking on maps or diagrams rendered in <canvas> elements
  • elements that don't have visible text or reliable CSS or XPath selectors

You can specify an x and y offset from the top-left corner of a reference element to click on:

js
I.click("#map", 129, 302)

This clicks 129 pixels to the right and 302 pixels down from the top-left corner of the #map element.

Alternatively, you can click using an offset from the viewport (the visible, scrolled area of the page):

js
I.click(500, 300)

This clicks 500 pixels to the right and 300 pixels down from the top-left corner of the viewport.

How UI-licious identifies elements to click ​

When multiple elements match a click target, UI-licious resolves the best match based on the following heuristics:

  1. Semantics: clickable elements such as links, buttons, and inputs are preferred
  2. Intent: matches based on visible text, ARIA labels, title and alt-text are preferred over surrounding text
  3. Context: elements closer to recently interacted elements are preferred

When clicks trigger page navigation ​

When a click triggers page navigation, UI-licious automatically waits for the new page to finish loading before executing the next command. This includes loading static assets such as images, CSS, and JavaScript files.

There is no need to add explicit waits using I.wait() after clicks that trigger navigation. The execution time of I.click() includes the time taken to load the page.

If the navigation opens a new tab, UI-licious automatically switches focus to the new tab. There is no need to call I.switchTab() manually.