Lupa

Appearance

Lupa API Reference / commands/locator / Locator

Class: Locator ​

Defined in: src/commands/locator.ts:475

A bridge to Playwright's Locator object, used to locate elements on the page and execute actions on them. It uses RPC calls to interact with the Playwright's Page object.

Not all Playwright's Locator actions are supported. Only actions that are relevant to testing are implemented.

Constructors ​

Constructor ​

new Locator(query): Locator

Defined in: src/commands/locator.ts:482

Creates a locator.

Parameters ​

query ​

LocatorQuery

The query to use to locate the element.

Returns ​

Locator

A locator.

Methods ​

blur() ​

blur(options?): Promise<void>

Defined in: src/commands/locator.ts:501

Calls blur on the element.

Parameters ​

options? ​

BlurOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the blur action is completed.

Example ​

Calling blur on the focused element.

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Focus me' }).blur()

check() ​

check(options?): Promise<void>

Defined in: src/commands/locator.ts:535

Ensure that checkbox or radio element is checked.

Parameters ​

options? ​

CheckOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the check action is completed.

Example ​

Checking a checkbox.

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ label: 'Subscribe' }).check()

clear() ​

clear(options?): Promise<void>

Defined in: src/commands/locator.ts:518

Clear the input field.

Parameters ​

options? ​

ClearOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the clear action is completed.

Example ​

Clearing the input field.

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ label: 'Email' }).clear()

click() ​

click(options?): Promise<void>

Defined in: src/commands/locator.ts:552

Clicks on the element.

Parameters ​

options? ​

ClickOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the click action is completed.

Example ​

Clicking on a button with text "Submit".

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Submit' }).click()

dblclick() ​

dblclick(options?): Promise<void>

Defined in: src/commands/locator.ts:587

Double clicks the element.

Parameters ​

options? ​

DoubleClickOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the double click action is completed.

Example ​

Double clicking on a button with text "Submit".

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Submit' }).dblclick()

dragTo() ​

dragTo(target, options?): Promise<void>

Defined in: src/commands/locator.ts:734

Drags the element to another target element or locator query.

Parameters ​

target ​

LocatorQuery | Locator

The target locator or locator query to drag to.

options? ​

DragToOptions

Optional settings to customize the drag-and-drop interaction.

Returns ​

Promise<void>

A promise that resolves when the drag action is completed.

Use ​

when

  • Performing a drag and drop interaction between two elements on the page (e.g., drag an item into a dropzone/trash bin).

Dont ​

use when

  • You want to simulate file drag events from the operating system. In those cases, use browser-side helpers like createFileDragEvent.

Example ​

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ testId: 'draggable-item' }).dragTo(query({ testId: 'trash-bin' }))

fill() ​

fill(text, options?): Promise<void>

Defined in: src/commands/locator.ts:570

Fills the input field.

Parameters ​

text ​

string

Value to set for the &lt;input&gt;, &lt;textarea&gt; or [contenteditable] element.

options? ​

FillOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the fill action is completed.

Example ​

Filling a text input with "admin" username.

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ placeholder: 'Username' }).fill('admin')

hover() ​

hover(options?): Promise<void>

Defined in: src/commands/locator.ts:604

Hovers over the element.

Parameters ​

options? ​

HoverOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the hover action is completed.

Example ​

Hovering over an element with text "Submit".

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Submit' }).hover()

press() ​

press(key, options?): Promise<void>

Defined in: src/commands/locator.ts:622

Presses the given key.

Parameters ​

key ​

string

The key to press.

options? ​

PressOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the press action is completed.

Example ​

Pressing the "Enter" key.

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Submit' }).press('Enter')

pressSequentially() ​

pressSequentially(text, options?): Promise<void>

Defined in: src/commands/locator.ts:648

Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.

Parameters ​

text ​

string

Value to type character by character.

options? ​

PressSequentiallyOptions

Optional settings to control the key press.

Returns ​

Promise<void>

A promise that resolves when the action is completed.

Use ​

when

  • Typing characters one by one into an element when the page has special keyboard handling (e.g. custom autocomplete, real-time input validation, or keyboard shortcuts).

Dont ​

use when

  • In most cases, you should use locator.fill() instead. fill() is faster, more reliable, and automatically clears the input.

Example ​

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ css: 'input' }).pressSequentially('Hello World', { delay: 100 })

screenshot() ​

screenshot(options): Promise<void>

Defined in: src/commands/locator.ts:671

Captures a screenshot of the element.

Parameters ​

options ​

ElementScreenshotOptions

Options for the screenshot, requires path.

Returns ​

Promise<void>

A promise that resolves when the screenshot is saved.

Use ​

when

  • You want to capture the visual state of a specific DOM element (e.g. a button, modal, or form).

Dont ​

use when

  • You want to capture the entire page or viewport. Use screenshot.take(...) instead.

Example ​

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Submit' }).screenshot({ path: 'screenshots/submit-button.png' })

selectOption() ​

selectOption(values, options?): Promise<string[]>

Defined in: src/commands/locator.ts:776

Selects one or multiple options in a &lt;select&gt; element.

Parameters ​

values ​

SelectOptionValues

Single value/object or array of values/objects to select.

options? ​

SelectOptionOptions

Optional settings to control actionability checks or timeouts.

Returns ​

Promise<string[]>

A promise that resolves to an array of option values that were successfully selected.

Use ​

when

  • Interacting with standard &lt;select&gt; dropdown controls in the UI.
  • Setting selection on a single or multi-select HTML &lt;select&gt; element.

Dont ​

use when

  • Interacting with custom UI select/dropdown component libraries (e.g. Material Select, custom divs/buttons dropdowns) that do not use native &lt;select&gt; and &lt;option&gt; elements. For those, click on the dropdown button and select options via standard click.

Examples ​

Selecting single option by value

typescript
import { query } from '@pawel-up/lupa/commands'

const selected = await query({ css: '#test-select' }).selectOption('2')

Selecting single option by label

typescript
import { query } from '@pawel-up/lupa/commands'

const selected = await query({ css: '#test-select' }).selectOption({ label: 'Two' })

Selecting multiple options in a `<select multiple>` dropdown

typescript
import { query } from '@pawel-up/lupa/commands'

const selected = await query({ css: '#multi-select' }).selectOption(['1', '3'])

setInputFiles() ​

setInputFiles(files, options?): Promise<void>

Defined in: src/commands/locator.ts:801

Sets the value of a file input to the specified file paths.

Parameters ​

files ​

string | string[]

A file path or array of file paths.

options? ​

SetInputFilesOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the file paths have been set.

Use ​

when

  • Setting files on a native HTML &lt;input type="file"&gt; element.

Dont ​

use when

  • Interacting with custom file upload buttons that trigger a native dialog rather than exposing the underlying file input directly. In those cases, use the fileChooser API instead.

Example ​

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ css: 'input[type=file]' }).setInputFiles('myfile.png')

tap() ​

tap(options?): Promise<void>

Defined in: src/commands/locator.ts:691

Taps the element.

Parameters ​

options? ​

TapOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the tap action is completed.

Example ​

Tapping on an element with text "Submit".

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Submit' }).tap()

uncheck() ​

uncheck(options?): Promise<void>

Defined in: src/commands/locator.ts:708

Ensure that checkbox or radio element is unchecked.

Parameters ​

options? ​

UncheckOptions

Optional settings to modify the action.

Returns ​

Promise<void>

A promise that resolves when the uncheck action is completed.

Example ​

Unchecking an element with text "Subscribe".

typescript
import { query } from '@pawel-up/lupa/commands'

await query({ text: 'Subscribe' }).uncheck()