import { Page } from '@playwright/test'; import { ScreenshotOptions } from '../enum/Options'; import { WebElement } from '@civitas-cerebrum/element-repository'; /** * Read-only accessors for element data: text, attributes, CSS, counts, and * screenshots. Pairs with `Interactions` (writes) and `Verifications` * (assertions) as the raw low-level layer. Users typically reach these through * `ElementInteractions.extract` or via `Steps.get*` / `ElementAction.get*`. * * Every method takes an `Element` from the repository. Wrap raw Playwright * Locators via `new WebElement(locator)` at the call site if you need to bridge. */ export declare class Extractions { private page; private ELEMENT_TIMEOUT; private utils; constructor(page: Page, timeout?: number); private softProbe; /** Safely retrieves and trims the text content of an element. */ getText(target: WebElement): Promise; /** Retrieves the value of a specified attribute. */ getAttribute(target: WebElement, attributeName: string): Promise; /** Retrieves the trimmed text content of every element matching the locator. */ getAllTexts(target: WebElement): Promise; /** Retrieves the current value of an input, textarea, or select element. */ getInputValue(target: WebElement): Promise; /** Returns the number of DOM elements matching the target. */ getCount(target: WebElement): Promise; /** Retrieves a computed CSS property value from an element. */ getCssProperty(target: WebElement, property: string): Promise; /** * Returns the element's bounding box (`{ x, y, width, height }` in CSS * pixels relative to the main frame), or `null` when the element is not * rendered. Use for layout/geometry assertions the DOM doesn't otherwise * surface: overlap, off-screen positioning, collapsed (`0×0`) regions. */ getBoundingBox(target: WebElement): Promise<{ x: number; y: number; width: number; height: number; } | null>; /** * Retrieves the raw HTML of an element. Defaults to `innerHTML`; set * `{ outer: true }` for `outerHTML` (the element tag plus its subtree). * * Reads after waiting for `attached` so the element exists in the DOM, * but does NOT wait for visibility — HTML inspection is a lower-level * read than the standard verification family. */ getHtml(target: WebElement, options?: { outer?: boolean; }): Promise; /** * Retrieves the HTML of the current page. Defaults to `document.body.innerHTML`; * set `{ outer: true }` for `document.documentElement.outerHTML` (the full * `...` document, including ``). * * Use this for page-level scans where no single element is the natural * scope — e.g. confirming an injected payload was HTML-escaped anywhere * in the rendered page. */ getPageHtml(options?: { outer?: boolean; }): Promise; /** * Retrieves the rendered text of the current page (`document.body.innerText`). * The text companion to {@link getPageHtml}. Use for page-level text * assertions where no single element is the natural scope — e.g. confirming * a 404 body renders known copy. */ getPageText(): Promise; /** * Returns every key currently set in `window.localStorage`. The enumerating * companion to {@link getLocalStorage} — use when the test needs to know * *which* keys exist (e.g. asserting a logout cleared all persisted state) * rather than reading a single known key. */ getLocalStorageKeys(): Promise; /** * Returns every key currently set in `window.sessionStorage`. The enumerating * companion to {@link getSessionStorage}. */ getSessionStorageKeys(): Promise; /** * Reads a value from the browser's `window.localStorage`. Returns `null` if * the key is missing — matches the native `localStorage.getItem` contract. * * Use for reading persisted UI state the framework cannot reach through * the DOM (theme preference, dismissed-banner flag, feature toggle, etc.). */ getLocalStorage(key: string): Promise; /** * Reads a value from the browser's `window.sessionStorage`. Returns `null` if * the key is missing — matches the native `sessionStorage.getItem` contract. */ getSessionStorage(key: string): Promise; /** * Writes a value to the browser's `window.localStorage` — the mutating * companion to {@link getLocalStorage}. Use to seed persisted state a test * depends on (a feature toggle, a dismissed-banner flag) or to drive * resilience checks with deliberately malformed values (e.g. corrupt JSON). * Matches the native `localStorage.setItem` contract (value coerced to string). */ setLocalStorage(key: string, value: string): Promise; /** * Writes a value to the browser's `window.sessionStorage` — the mutating * companion to {@link getSessionStorage}. Matches the native * `sessionStorage.setItem` contract (value coerced to string). */ setSessionStorage(key: string, value: string): Promise; /** * Removes a single key from `window.localStorage`. No-op when the key is * absent — matches the native `localStorage.removeItem` contract. */ removeLocalStorage(key: string): Promise; /** * Removes a single key from `window.sessionStorage`. No-op when the key is * absent — matches the native `sessionStorage.removeItem` contract. */ removeSessionStorage(key: string): Promise; /** * Removes every key from `window.localStorage`. Matches the native * `localStorage.clear` contract. */ clearLocalStorage(): Promise; /** * Removes every key from `window.sessionStorage`. Matches the native * `sessionStorage.clear` contract. */ clearSessionStorage(): Promise; /** * Reads a value from the `window` object by dotted path — e.g. * `'__XSS_FIRED'`, `'dataLayer.length'`, `'document.title'`. Walks the path * key-by-key, returning `undefined` the moment any intermediate segment is * `null`/`undefined` (so a missing path is `undefined`, never a thrown error). * * Use for asserting window-level JS state the DOM doesn't surface: analytics * layers, injected flags, feature toggles, XSS-fired sentinels, etc. * * Values cross the `page.evaluate` serialization boundary: functions and * symbols arrive as `undefined`. To assert such a property EXISTS, use * `verifyWindowProperty(path, { present: true })`, which detects them in-page. */ getWindowProperty(path: string): Promise; /** * Writes a value onto the `window` object by dotted path, creating any * missing intermediate objects along the way — e.g. * `setWindowProperty('__test.flag', true)` ensures `window.__test` exists * then sets `.flag`. The mutating companion to {@link getWindowProperty}; * use to seed window-level state a test depends on. */ setWindowProperty(path: string, value: unknown): Promise; /** * The single typed escape hatch for arbitrary in-page JavaScript: * `page.evaluate(fn, arg)`. This raw interaction does NOT log — the logged * wrapper is `Steps.evaluateScript`; prefer it (and the targeted steps * `getWindowProperty`, `verifyWindowProperty`, the matcher tree, scoped * queries) which stay named, retrying, and grep-able. Reach here only when * no targeted step expresses the read. `fn` may be sync or `async`. * * @param fn A function serialised and run in the browser context. * @param arg An optional, serialisable argument passed to `fn`. */ evaluateScript(fn: (arg?: unknown) => T | Promise, arg?: unknown): Promise; /** Captures a screenshot of the full page or a specific element. */ screenshot(target?: WebElement, options?: ScreenshotOptions): Promise; }