Implementation:Getgauge Taiko Highlight
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, User_Interaction |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Concrete tool for visually highlighting and un-highlighting web page elements for debugging purposes provided by the Taiko browser automation library.
Description
This module exports two functions -- `highlight` and `clearHighlights` -- that apply and remove a visual red outline on DOM elements to aid in test debugging and development.
- `highlight(selector, args)`** works through the following algorithm:
1. **Element Discovery:** Calls `findElements(selector)` to locate all matching DOM elements, then filters the results through `handleRelativeSearch(elems, args)` to apply any proximity-based narrowing (e.g., "near", "above", "below").
2. **Style Injection:** Executes a function on the first matching element via `runtimeHandler.runtimeCallFunctionOn`. Inside the browser context, it first checks whether a `<style>` tag with the ID `taiko_highlight` already exists in the element's root node. If not, it creates one containing the CSS rule `.taiko_highlight_style { outline: 0.5em solid red; }` and appends it to the appropriate head: the `document.head` for elements in the main document, or the `ShadowRoot` itself for elements inside shadow DOM. This ensures the highlight style is available regardless of DOM encapsulation.
3. **Class Application:** Adds the CSS class `taiko_highlight_style` to the target element. For text nodes (`Node.TEXT_NODE`), the class is added to the parent element instead, since text nodes cannot have CSS classes directly.
- `clearHighlights()`** removes all active highlights by:
1. Querying all elements with the class `taiko_highlight_style` in the main document via `getElementsByClassName` and removing the class from each. 2. Iterating over all elements in the document and checking each for a `shadowRoot`. For any element with a shadow root, it queries within that shadow root for elements with the highlight class and removes it.
This two-pass approach ensures highlights are cleared from both the light DOM and all shadow DOM boundaries.
Usage
Use `highlight` during test development to visually verify which element a selector is targeting, especially when debugging complex selectors or proximity searches. Use `clearHighlights` to reset the visual state after inspection. These functions are also called internally by other Taiko actions in headful mode to provide visual feedback during automated interactions.
Code Reference
Source Location
- Repository: Getgauge_Taiko
- File: lib/actions/highlight.js
- Lines: 1-58
Signature
const highlight = async (selector, args) => { ... }
const clearHighlights = async () => { ... }
Import
const { highlight, clearHighlights } = require('taiko');
I/O Contract
Inputs
highlight
| Name | Type | Required | Description |
|---|---|---|---|
| selector | Selector / Element / string | Yes | The target element to highlight. Accepts any Taiko selector type used by `findElements`. |
| args | Array | No | Optional proximity search arguments (e.g., `toRightOf`, `near`) passed to `handleRelativeSearch` to narrow down the matched elements. |
clearHighlights
| Name | Type | Required | Description |
|---|---|---|---|
| (none) | -- | -- | This function takes no parameters. |
Outputs
| Name | Type | Description |
|---|---|---|
| highlight result | Promise<string> | A human-readable confirmation, e.g. `"Highlighted the <element description>"`. |
| clearHighlights result | Promise<string> | The fixed string `"Cleared all highlights for this page."`. |
Usage Examples
Basic Usage
const { openBrowser, goto, highlight, clearHighlights, $, closeBrowser } = require('taiko');
(async () => {
await openBrowser({ headless: false });
await goto('https://example.com');
// Highlight a specific element to visually confirm the selector target
await highlight($('#main-content'));
// Highlight an element using proximity search
await highlight('Submit', toRightOf('Cancel'));
// Clear all highlights when done inspecting
await clearHighlights();
await closeBrowser();
})();