UI-licious Documentation

Appearance

Why UI-licious? ​

Automated testing was supposed to give engineering teams confidence to ship fast without breaking things.

Instead, for many teams, automated end-to-end testing has become a maintenance trap. Test suites that pass today fail tomorrow—not because the application is broken, but because a developer renamed a CSS class, wrapped a button inside a new <div>, or tweaked an internal DOM hierarchy.

UI-licious was built to solve this fundamental problem.

The Maintenance Trap in Web Testing ​

In most test automation tools, tests are tightly coupled to the internal implementation details of the webpage:

js
// Selenium WebDriver
await driver.findElement(
    By.xpath("//div[@id='app']/div[2]/form/div[3]/button[contains(@class, 'btn-primary-2X8w')]")
).click();

When tests rely on fragile XPath expressions, CSS selectors, or autogenerated component IDs, they break whenever:

  • A frontend framework or component library is updated.
  • Utility classes change (such as migrating to Tailwind CSS).
  • A redesign alters the HTML markup hierarchy.
  • Autogenerated DOM IDs change between builds.

Studies and industry surveys consistently show that engineering teams spend up to 80% of their automation time maintaining existing tests rather than expanding test coverage for new features.

When tests become too brittle to trust, teams stop running them, and testing regresses back to slow, costly manual QA.

The UI-licious Approach: Test the User Journey, Not the HTML ​

Users don't interact with your website by querying the DOM. They don't look for div#main > form > button.btn-lg.

Users look for visual cues: "Sign In", "Add to Cart", or the input field labeled "Email Address".

Our testing philosophy is anchored in a simple mantra: Test the user journey, not the HTML.

UI-licious tests your application through the eyes of the user:

js
// UI-licious
I.fill("Email Address", "[email protected]")
I.fill("Password", "secret123")
I.click("Sign In")
I.see("Welcome back")

How the Semantic Engine Works ​

Under the hood, UI-licious uses an intelligent semantic engine that inspects the page much like a human does:

  1. Visual Text & Labels: Matches visible text on buttons, headings, links, and paragraphs.
  2. Form Associations: Automatically connects <label> elements, aria-label, aria-labelledby, and placeholder text to their corresponding form inputs.
  3. Accessibility Attributes: Inspects accessibility roles, title attributes, and hover tooltips for icon-only buttons (such as navigation menus or search icons).
  4. Automatic Shadow DOM Traversal: Recursively pierces open shadow roots without requiring custom JavaScript or chained locators.

Dynamic Runtime Resolution vs Hardcoded Selectors ​

In frameworks like Playwright or Selenium, tests statically bind to a hardcoded selector chosen at author-time:

js
// Rigid author-time binding: fails if an ID, tag, or wrapper changes
await page.locator("#auth-form > div:nth-child(2) > input.user-email-input").fill("...");

If anything in that DOM path alters during a release, the test fails immediately—even if the UI looks identical to the user.

In UI-licious, element targeting is dynamically resolved at runtime:

js
I.fill("Email", "[email protected]")

When this command runs, UI-licious doesn't evaluate a single hardcoded path. Instead, the runtime engine:

  • Scans candidate elements across the live DOM and open Shadow DOM trees.
  • Evaluates visual labels, <label for>, placeholder text, ARIA attributes, and spatial text proximity.
  • Scores and disambiguates candidate matches based on multiple factors—such as match exactness (e.g. prioritizing an exact match for "Sign In" over "Sign in to view your dashboard"), element semantics (<button> vs generic <div>), and proximity to recently interacted elements (see the Targeting Elements Guide).
  • Resolves the target element dynamically at runtime.

This dynamic runtime resolution makes UI-licious tests dramatically more robust. If your frontend team refactors an input into a custom Web Component, wraps it in a new layout container, or migrates from <label> tags to aria-label attributes, UI-licious resolves the correct target element at runtime without requiring any updates to your test script.

Automated Telemetry, Less Boilerplate ​

In developer frameworks like Selenium or Playwright, writing a test script often involves writing dozens of lines of utility code that have nothing to do with the actual test logic:

js
// Playwright: Cluttered with logging and telemetry boilerplate
test("user checkout", async ({ page }) => {
    console.log("Navigating to checkout, current URL:", page.url());
    await page.screenshot({ path: "screenshots/before-checkout.png" });
    
    // Check open tabs and document state
    const pages = page.context().pages();
    console.log(`Open tabs: ${pages.length}, active title: ${await page.title()}`);
    
    await page.getByRole("button", { name: "Place Order" }).click();
    
    // Capture state after click for debugging
    await page.waitForLoadState("networkidle");
    await page.screenshot({ path: "screenshots/after-checkout.png" });
    console.log("Order placed at URL:", page.url());
});

All this boilerplate code:

  • Obscures the test logic: The core user story is buried underneath instrumentation hooks.
  • Inflates maintenance costs: Screenshot paths, custom loggers, and URL trackers must be maintained across hundreds of tests.
  • Creates inconsistent reporting: Different engineers log different details, making test failures harder to debug uniformly.

Pure Test Logic in UI-licious ​

UI-licious eliminates telemetry boilerplate by design. You write only the steps that represent the user journey:

js
// UI-licious: 100% focused on pure test logic
I.goTo("https://store.example.com/checkout")
I.click("Place Order")
I.see("Thank you for your order!")

Behind the scenes, UI-licious automatically captures comprehensive telemetry at every single command:

  • High-Resolution Screenshots: Screenshots are captured automatically at each step (and highlighted before clicks), showing exactly what the screen looked like.
  • Page URL & Title: The current URL and document title are automatically recorded with every command.
  • Open Tabs & Active Windows: Tracks window handles, open tabs, and active context transitions automatically.
  • Step Timing & Network Status: Execution duration, network requests, and console errors are logged transparently without manual instrumentation.

Because telemetry is handled automatically by the test runner, your scripts remain clean, concise, and focused entirely on the user journey.

Coroutine Synchronization: Clean Code Without 'await' Clutter ​

In standard JavaScript browser automation frameworks, every command returns a Promise. This forces developers to declare functions async and prepend await before literally every interaction:

js
// Standard async/await: High cognitive load and easy to miss
await page.goto("https://store.example.com");
await page.locator("#search").fill("laptop");
await page.locator("#submit").click();
await expect(page.locator(".results")).toBeVisible();

If you accidentally omit a single await, JavaScript won't wait for that step to finish. The next command fires prematurely, triggering race conditions, out-of-order execution, or unhandled promise rejections that are notoriously difficult to track down.

UI-licious solves this by executing test commands with coroutine synchronization. Under the hood, the UI-licious runtime manages asynchronous browser interactions transparently:

js
// UI-licious: Clean, linear procedural execution
I.goTo("https://store.example.com")
I.fill("Search", "laptop")
I.click("Submit")
I.see("results")

Commands execute in strict procedural order without requiring you to pepper await all over your code. This eliminates an entire class of asynchronous timing bugs, simplifies debugging, and keeps your test scripts concise and readable.

Tests as Living Documentation (No Cucumber / Gherkin Overhead) ​

Many organizations attempt to make test suites readable by layering Behavior-Driven Development (BDD) frameworks—such as Cucumber or Gherkin (Given / When / Then)—on top of Selenium or Playwright.

While the intention is good, this introduces a heavy maintenance tax:

  • Teams must write and maintain separate Gherkin .feature files.
  • Engineers must maintain complex "glue code" step definitions with fragile regular expressions to map each sentence to underlying code.
  • Test failures require debugging three distinct layers: the feature file, the step definition glue code, and the underlying page object.

UI-licious eliminates the need for an extra abstraction layer. Because UI-licious commands read like plain English, the test script itself serves directly as living documentation:

js
// Clean, executable documentation that anyone can understand
I.goTo("https://store.example.com")
I.click("Shop")
I.click("Classic T-Shirt")
I.click("Add to Cart")
I.click("Checkout")

I.fill("Shipping Address", "123 Market St")
I.click("Place Order")

I.see("Thank you for your order!")

Product managers, QA analysts, and developers can all read, review, and collaborate on the exact same test file. Non-programmers can write tests without learning complex test frameworks, while developers retain full JavaScript capabilities (if, loops, custom helper functions, plugins) whenever advanced logic is required.

Tool Comparisons ​

To see how UI-licious compares directly to specific developer frameworks and legacy automation tools, explore our detailed head-to-head comparisons:

  • UI-licious vs Selenium — How UI-licious eliminates NoSuchElementException, driver compatibility issues, and fragile XPath locators.
  • UI-licious vs Playwright — Comparing developer-first code automation with collaborative, semantic cloud testing.

Next Steps ​