element.md

Element

Element has a "lazy" interface (as it was in protractor). The element is not resolved until an action is performed on it.

All examples work identically with both playwrightWD and seleniumWD.

• Selector strategies
• Child elements
• click
• doubleClick
• sendKeys
• clear
• clearViaBackspace
• pressEnter
• hover
• hoverByElementCoordinate
• clickByElementCoordinate
• getElementCoordinates
• focus
• getText
• getTagName
• getAttribute
• getCssValue
• getRect
• isDisplayed
• isPresent
• isEnabled
• isSelected
• submit
• selectOption
• scrollIntoView
• takeScreenshot
• getEngineElement
• locator

---

Selector strategies

const { playwrightWD } = require('promod');
const { $ } = playwrightWD;

const byCss = $('.class #id div a[href*="link"]');
const byXpath = $('xpath=.//div[@data-test="id"]/span');
const byJS = $(() => document.querySelector('div > span'));
const byCustom = $({ query: 'button', text: 'Submit' });
const byCustomRegex = $({ query: 'button', rg: 'Sub.*' });

Child elements

Elements can create child $ and $$ from themselves, scoping the search to the parent element.

const form = $('form');
const input = form.$('input');           // single child element
const buttons = form.$$('button');       // child elements collection

click

const button = $('button');

await button.click();                                  // regular click
await button.click({ withScroll: true });              // scroll into view first
await button.click({ allowForceIfIntercepted: true }); // retry via coordinates if intercepted
await button.click({ force: true });                   // force click via coordinates
await button.click({ button: 'right' });               // right click

Option	Type	Description
withScroll	boolean	Scroll element into view before clicking
allowForceIfIntercepted	boolean	Retry via coordinates if click is intercepted
force	boolean	Click via coordinates directly
button	'left' | 'right' | 'middle'	Mouse button
clickCount	number	Number of clicks
delay	number	Delay between mousedown and mouseup
modifiers	Array<'Alt'|'Control'|'Meta'|'Shift'>	Modifier keys
position	{ x: number; y: number }	Click position relative to element
timeout	number	Timeout in ms

doubleClick

const button = $('button');

await button.doubleClick();
await button.doubleClick({ withScroll: true });

Accepts the same options as click (except clickCount).

sendKeys

const input = $('input');

await input.sendKeys('hello world');
await input.sendKeys(42);
await input.sendKeys('hello', true); // use fill mode (Playwright: clears first then fills)

clear

const input = $('input');
await input.clear();

clearViaBackspace

Clears input by pressing backspace repeatedly.

const input = $('input');
await input.sendKeys('hello');
await input.clearViaBackspace(5, true); // 5 backspaces, focus first

Parameter	Type	Description
repeat	number	Number of backspace presses (default 1)
focus	boolean	Focus/click element first

pressEnter

const input = $('input');
await input.sendKeys('search query');
await input.pressEnter();       // focus first (default)
await input.pressEnter(false);  // without focusing

hover

const button = $('button');

await button.hover();
await button.hover({ force: true });

hoverByElementCoordinate

Moves the mouse to a specific position relative to the element.

const el = $('div');
await el.hoverByElementCoordinate('center');
await el.hoverByElementCoordinate('right-top');

Positions: 'center', 'center-top', 'center-bottom', 'center-right', 'center-left', 'right-top', 'right-bottom', 'left-top', 'left-bottom'

clickByElementCoordinate

Clicks at a specific position relative to the element.

const el = $('div');
await el.clickByElementCoordinate('center');
await el.clickByElementCoordinate('left-top');

getElementCoordinates

Returns the x/y coordinates of a specific position on the element.

const { x, y } = await $('div').getElementCoordinates('center');

focus

const input = $('input');
await input.focus();

getText

const text = await $('h1').getText();

getTagName

const tag = await $('h1').getTagName(); // 'h1'

getAttribute

const href = await $('a').getAttribute('href');
const dataId = await $('div').getAttribute('data-id');

getCssValue

Returns the computed CSS property value.

const color = await $('button').getCssValue('color');
const fontSize = await $('h1').getCssValue('font-size');

getRect

Returns the element bounding box.

const { x, y, width, height } = await $('div').getRect();

isDisplayed

const visible = await $('button').isDisplayed(); // true | false

isPresent

Checks if the element exists in the DOM.

const exists = await $('button').isPresent(); // true | false

isEnabled

const enabled = await $('button').isEnabled(); // true | false

isSelected

const selected = await $('input[type="checkbox"]').isSelected(); // true | false

submit

await $('form').submit();

selectOption

Works with <select> elements.

const select = $('select');

// By visible text
await select.selectOption('Option text');

// By value attribute
await select.selectOption({ value: 'opt1' });

// By label attribute
await select.selectOption({ label: 'Option Label' });

// By index
await select.selectOption({ index: 2 });

scrollIntoView

const el = $('div');

await el.scrollIntoView();          // default scroll
await el.scrollIntoView('start');   // scroll to top of viewport
await el.scrollIntoView('end');     // scroll to bottom of viewport
await el.scrollIntoView('center');  // scroll to center of viewport
await el.scrollIntoView('nearest'); // scroll to nearest edge

takeScreenshot

const screenshot = await $('form').takeScreenshot();

getEngineElement

Returns the underlying native engine element (Playwright Locator / Selenium WebElement).

const nativeElement = await $('button').getEngineElement();

locator

Returns the selector information used to find this element.

const info = $('button').locator(); // { value: 'button' }