Element API

The ElementHandle provides methods for interacting with individual DOM elements.

Getting an ElementHandle

// Via browser.find()
const element = browser.find('#my-element');
const button = browser.find(By.text('Submit'));

// Element-scoped operations
const input = browser.find('#input');
await input.fill('text');
await input.press('Enter');

Tip: Use browser.locator(selector) instead of find() when you need composition, filtering, or indexed access (.nth(), .filter(), .all()). See Selectors & Locators.

Methods

click()

Click on the element.

await browser.find('#button').click();

fill(text, options?)

Fill a text input with the given value.

await browser.find('#username').fill('testuser');

// With options
await browser.find('#email').fill('test@example.com', { timeout: 5000 });

clear(options?)

Clear the input value.

await browser.find('#search').clear();

press(key)

Press a keyboard key while focused on the element.

await browser.find('#input').press('Enter');
await browser.find('#textarea').press('Tab');
await browser.find('#field').press('Backspace');

Available keys: 'Enter', 'Tab', 'Escape', 'Backspace', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', etc.

hover(options?)

Move the mouse to hover over the element.

// Reveal a tooltip
await browser.find('#info-icon').hover();

// Open a dropdown menu on hover
await browser.find('.menu-trigger').hover();
await browser.find('.menu-item').click();

select(value, options?)

Select an option from a <select> dropdown by value.

await browser.find('#country').select('us');
await browser.find('#language').select('en');

⚠️ Note: This method only works on <select> elements. It will throw an error if used on other element types.

text()

Get the visible text content of the element.

const message = await browser.find('#result').text();
console.log(message); // "Success!"

value()

Get the current value of an input element.

const inputValue = await browser.find('#email').value();

tagName()

Get the element tag name.

const tag = await browser.find('#submit').tagName(); // "button"

getAttribute(name)

Get an attribute value from the element.

const href = await browser.find('a.link').getAttribute('href');
const disabled = await browser.find('#btn').getAttribute('disabled');

isVisible()

Check if the element is visible on the page.

const visible = await browser.find('#modal').isVisible();
if (visible) {
  await browser.find('#modal .close').click();
}

isEnabled()

Check if the element is enabled (not disabled).

const enabled = await browser.find('#submit').isEnabled();

isChecked()

Check if a checkbox or radio button is checked.

const checked = await browser.find('#agree-terms').isChecked();

boundingBox()

Get the element's position and size.

const box = await browser.find('#target').boundingBox();
// { x: 100, y: 200, width: 300, height: 50 }

screenshot(opts?)

Take a screenshot of just this element. Returns the PNG bytes as a Buffer; pass path to also write the file in one step.

// Get as buffer
const buffer = await browser.find('#chart').screenshot();

// Save to file
await browser.find('#logo').screenshot({ path: 'logo.png' });

expect()

Get an ExpectApi scoped to this element for assertions.

await browser.find('#message').expect().toHaveText('Success');
await browser.find('#input').expect().toHaveValue('test@example.com');

setInputFiles(filePaths, options?)

Set files on an <input type="file">.

await browser.find('#avatar').setInputFiles('/absolute/path/avatar.png');
await browser.find('#photos').setInputFiles([
  '/absolute/path/one.jpg',
  '/absolute/path/two.jpg',
]);

evaluate(fn, ...args)

Run JavaScript with this element as the first argument.

const tag = await browser.find('#submit').evaluate(el => el.tagName.toLowerCase());
const active = await browser
  .find('#submit')
  .evaluate((el, cls) => el.classList.contains(cls), 'active');

a11y

Run an accessibility audit scoped to this element and its descendants.

const result = await browser.find('#checkout').a11y.audit();

Examples

Form Filling

await browser.find('#first-name').fill('John');
await browser.find('#last-name').fill('Doe');
await browser.find('#email').fill('john@example.com');
await browser.find('#country').select('us');
await browser.find('#agree-terms').click();
await browser.find('#submit').click();

Hover Interactions

// Reveal dropdown menu
await browser.find('#user-menu').hover();
await browser.find('#logout-link').click();

Conditional Actions

const modal = browser.find('#cookie-banner');
if (await modal.isVisible()) {
  await browser.find('#accept-cookies').click();
}

Getting Element State

const button = browser.find('#submit');

const text = await button.text();
const enabled = await button.isEnabled();
const visible = await button.isVisible();

console.log({ text, enabled, visible });