@toolstackhq/cdpwright 1.2.0 → 1.3.0

package/dist/cli.js

@@ -419,27 +419,77 @@ function serializeShadowDomHelpers() {
 // src/core/Locator.ts
 var Locator = class {
   frame;
-  selector;
-  options;
-  constructor(frame, selector, options = {}) {
+  query;
+  constructor(frame, query) {
     this.frame = frame;
-    this.selector = selector;
-    this.options = options;
+    this.query = query;
+  }
+  getEvents() {
+    return this.frame.getEvents();
+  }
+  getFrameId() {
+    return this.frame.id;
+  }
+  describe() {
+    switch (this.query.kind) {
+      case "selector":
+        return this.query.selector;
+      case "text":
+        return typeof this.query.text === "string" ? `text=${JSON.stringify(this.query.text)}` : `text=${this.query.text.toString()}`;
+      case "role":
+        return `role=${this.query.role}${this.query.options?.name ? ` name=${typeof this.query.options.name === "string" ? JSON.stringify(this.query.options.name) : this.query.options.name.toString()}` : ""}`;
+    }
   }
   async click(options = {}) {
-    return this.frame.click(this.selector, { ...this.options, ...options });
+    return this.frame.clickLocator(this.query, { ...this.queryTimeoutOptions(), ...options });
   }
   async dblclick(options = {}) {
-    return this.frame.dblclick(this.selector, { ...this.options, ...options });
+    return this.frame.dblclickLocator(this.query, { ...this.queryTimeoutOptions(), ...options });
   }
   async type(text, options = {}) {
-    return this.frame.type(this.selector, text, { ...this.options, ...options });
+    return this.frame.typeLocator(this.query, text, { ...this.queryTimeoutOptions(), ...options });
   }
   async exists() {
-    return this.frame.exists(this.selector, this.options);
+    return this.frame.existsLocator(this.query);
+  }
+  async isVisible() {
+    return this.frame.isVisibleLocator(this.query);
+  }
+  async isEnabled() {
+    return this.frame.isEnabledLocator(this.query);
+  }
+  async isChecked() {
+    return this.frame.isCheckedLocator(this.query);
   }
   async text() {
-    return this.frame.text(this.selector, this.options);
+    return this.frame.textLocator(this.query);
+  }
+  async value() {
+    return this.frame.valueLocator(this.query);
+  }
+  async attribute(name) {
+    return this.frame.attributeLocator(this.query, name);
+  }
+  async classes() {
+    return this.frame.classesLocator(this.query);
+  }
+  async css(property) {
+    return this.frame.cssLocator(this.query, property);
+  }
+  async hasFocus() {
+    return this.frame.hasFocusLocator(this.query);
+  }
+  async isInViewport(fully = false) {
+    return this.frame.isInViewportLocator(this.query, fully);
+  }
+  async isEditable() {
+    return this.frame.isEditableLocator(this.query);
+  }
+  async count() {
+    return this.frame.countLocator(this.query);
+  }
+  queryTimeoutOptions() {
+    return "options" in this.query && this.query.options?.timeoutMs ? { timeoutMs: this.query.options.timeoutMs } : {};
   }
 };
 
@@ -471,6 +521,9 @@ var Frame = class {
     this.url = meta.url;
     this.parentId = meta.parentId;
   }
+  getEvents() {
+    return this.events;
+  }
   async evaluate(fnOrString, ...args) {
     return this.evaluateInContext(fnOrString, args);
   }
@@ -487,7 +540,13 @@ var Frame = class {
     return this.querySelectorAllInternal(selector, options, true);
   }
   locator(selector, options = {}) {
-    return new Locator(this, selector, options);
+    return new Locator(this, { kind: "selector", selector, options });
+  }
+  getByText(text, options = {}) {
+    return new Locator(this, { kind: "text", text, options });
+  }
+  getByRole(role, options = {}) {
+    return new Locator(this, { kind: "role", role, options });
   }
   async click(selector, options = {}) {
     await this.performClick(selector, options, false);
@@ -922,6 +981,176 @@ var Frame = class {
     const box = await this.resolveElementBox(selector, options);
     return Boolean(box && box.visible);
   }
+  async clickLocator(query, options = {}) {
+    await this.performClickLocator(query, options, false);
+  }
+  async dblclickLocator(query, options = {}) {
+    await this.performClickLocator(query, options, true);
+  }
+  async typeLocator(query, text, options = {}) {
+    const start = Date.now();
+    const description = this.locatorDescription(query);
+    this.events.emit("action:start", { name: "type", selector: description, frameId: this.id, sensitive: options.sensitive });
+    await waitFor(async () => {
+      const box = await this.resolveLocatorElementBox(query, options);
+      if (!box || !box.visible) {
+        return false;
+      }
+      return true;
+    }, { timeoutMs: options.timeoutMs ?? this.defaultTimeout, description: `type ${description}` });
+    const focusExpression = this.buildLocatorExpression(query, `
+      if (!el) {
+        return;
+      }
+      el.focus();
+    `);
+    const focusParams = {
+      expression: focusExpression,
+      returnByValue: true
+    };
+    if (this.contextId) {
+      focusParams.contextId = this.contextId;
+    }
+    await this.session.send("Runtime.evaluate", focusParams);
+    await this.session.send("Input.insertText", { text });
+    const duration = Date.now() - start;
+    this.events.emit("action:end", { name: "type", selector: description, frameId: this.id, durationMs: duration, sensitive: options.sensitive });
+    this.logger.debug("Type", description, `${duration}ms`);
+  }
+  async existsLocator(query) {
+    return Boolean(await this.evalOnLocator(query, false, `
+      return Boolean(el);
+    `));
+  }
+  async isVisibleLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const rect = el.getBoundingClientRect();
+      const style = window.getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity || "1") > 0;
+    `);
+  }
+  async isEnabledLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const disabled = Boolean(el.disabled) || el.hasAttribute("disabled");
+      const ariaDisabled = el.getAttribute && el.getAttribute("aria-disabled") === "true";
+      return !(disabled || ariaDisabled);
+    `);
+  }
+  async isCheckedLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const aria = el.getAttribute && el.getAttribute("aria-checked");
+      if (aria === "true") {
+        return true;
+      }
+      if (aria === "false") {
+        return false;
+      }
+      if ("checked" in el) {
+        return Boolean(el.checked);
+      }
+      return null;
+    `);
+  }
+  async textLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      if (el instanceof HTMLInputElement) {
+        const type = (el.getAttribute("type") || "text").toLowerCase();
+        if (type === "button" || type === "submit" || type === "reset") {
+          return el.value || "";
+        }
+      }
+      return el.textContent || "";
+    `);
+  }
+  async valueLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      if ("value" in el) {
+        return el.value ?? "";
+      }
+      return el.getAttribute("value");
+    `);
+  }
+  async attributeLocator(query, name) {
+    return this.evalOnLocator(query, false, `
+      if (!el || !(el instanceof Element)) {
+        return null;
+      }
+      return el.getAttribute(${JSON.stringify(name)});
+    `);
+  }
+  async classesLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      if (!el.classList) {
+        return [];
+      }
+      return Array.from(el.classList);
+    `);
+  }
+  async cssLocator(query, property) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const style = window.getComputedStyle(el);
+      return style.getPropertyValue(${JSON.stringify(property)}) || "";
+    `);
+  }
+  async hasFocusLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      return document.activeElement === el;
+    `);
+  }
+  async isInViewportLocator(query, fully = false) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const rect = el.getBoundingClientRect();
+      const viewWidth = window.innerWidth || document.documentElement.clientWidth;
+      const viewHeight = window.innerHeight || document.documentElement.clientHeight;
+      if (${fully ? "true" : "false"}) {
+        return rect.top >= 0 && rect.left >= 0 && rect.bottom <= viewHeight && rect.right <= viewWidth;
+      }
+      return rect.bottom > 0 && rect.right > 0 && rect.top < viewHeight && rect.left < viewWidth;
+    `);
+  }
+  async isEditableLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const disabled = Boolean(el.disabled) || el.hasAttribute("disabled");
+      const readOnly = Boolean(el.readOnly) || el.hasAttribute("readonly");
+      const ariaDisabled = el.getAttribute && el.getAttribute("aria-disabled") === "true";
+      return !(disabled || readOnly || ariaDisabled);
+    `);
+  }
+  async countLocator(query) {
+    return this.evalOnLocator(query, true, `
+      return elements.length;
+    `);
+  }
   async text(selector, options = {}) {
     return this.evalOnSelector(selector, options, false, `
       if (!el) {
@@ -1103,6 +1332,263 @@ var Frame = class {
       return !(disabled || readOnly || ariaDisabled);
     `);
   }
+  async performClickLocator(query, options, isDouble) {
+    const start = Date.now();
+    const actionName = isDouble ? "dblclick" : "click";
+    const description = this.locatorDescription(query);
+    this.events.emit("action:start", { name: actionName, selector: description, frameId: this.id });
+    const box = await waitFor(async () => {
+      const result = await this.resolveLocatorElementBox(query, options);
+      if (!result || !result.visible) {
+        return null;
+      }
+      return result;
+    }, { timeoutMs: options.timeoutMs ?? this.defaultTimeout, description: `${actionName} ${description}` });
+    const centerX = box.x + box.width / 2;
+    const centerY = box.y + box.height / 2;
+    await this.session.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: centerX, y: centerY });
+    await this.session.send("Input.dispatchMouseEvent", { type: "mousePressed", x: centerX, y: centerY, button: "left", clickCount: 1, buttons: 1 });
+    await this.session.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: centerX, y: centerY, button: "left", clickCount: 1, buttons: 0 });
+    if (isDouble) {
+      await this.session.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: centerX, y: centerY });
+      await this.session.send("Input.dispatchMouseEvent", { type: "mousePressed", x: centerX, y: centerY, button: "left", clickCount: 2, buttons: 1 });
+      await this.session.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: centerX, y: centerY, button: "left", clickCount: 2, buttons: 0 });
+    }
+    const duration = Date.now() - start;
+    this.events.emit("action:end", { name: actionName, selector: description, frameId: this.id, durationMs: duration });
+    this.logger.debug("Click", description, `${duration}ms`);
+  }
+  locatorDescription(query) {
+    switch (query.kind) {
+      case "selector":
+        return query.selector;
+      case "text":
+        return typeof query.text === "string" ? `text=${JSON.stringify(query.text)}` : `text=${query.text.toString()}`;
+      case "role":
+        return `role=${query.role}${query.options?.name ? ` name=${typeof query.options.name === "string" ? JSON.stringify(query.options.name) : query.options.name.toString()}` : ""}`;
+    }
+  }
+  async resolveLocatorElementBox(query, options) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      el.scrollIntoView({ block: "center", inline: "center" });
+      const rect = el.getBoundingClientRect();
+      const style = window.getComputedStyle(el);
+      return {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+        visible: rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity || "1") > 0
+      };
+    `);
+  }
+  async evalOnLocator(query, all, body) {
+    const expression = this.buildLocatorExpression(query, body, all);
+    const params = {
+      expression,
+      returnByValue: true
+    };
+    if (this.contextId) {
+      params.contextId = this.contextId;
+    }
+    const result = await this.session.send("Runtime.evaluate", params);
+    return result.result.value;
+  }
+  buildLocatorExpression(query, body, all = false) {
+    const helpers = serializeShadowDomHelpers();
+    const serializedQuery = this.serializeLocatorQuery(query);
+    return `(function() {
+      const querySelectorAllDeep = ${helpers.querySelectorAllDeep};
+      const normalizeWhitespace = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
+      const cssEscape = (value) => {
+        if (typeof CSS !== "undefined" && CSS.escape) return CSS.escape(value);
+        return String(value).replace(/[^a-zA-Z0-9_-]/g, (c) => "\\\\" + c.charCodeAt(0).toString(16) + " ");
+      };
+      const textFromElement = (el) => {
+        if (!el) return "";
+        if (el instanceof HTMLInputElement) {
+          const type = (el.getAttribute("type") || "").toLowerCase();
+          if (type === "button" || type === "submit" || type === "reset" || type === "image") {
+            return el.value || el.getAttribute("alt") || "";
+          }
+        }
+        return el.textContent || "";
+      };
+      const isHidden = (el) => {
+        if (!el || !(el instanceof Element)) return true;
+        const style = window.getComputedStyle(el);
+        if (el.hidden || el.getAttribute("aria-hidden") === "true") return true;
+        return style.display === "none" || style.visibility === "hidden" || Number(style.opacity || "1") <= 0;
+      };
+      const getLabelText = (el) => {
+        if (!el || !(el instanceof Element)) return "";
+        const ariaLabel = el.getAttribute("aria-label");
+        if (ariaLabel) return normalizeWhitespace(ariaLabel);
+        const labelledBy = el.getAttribute("aria-labelledby");
+        if (labelledBy) {
+          const parts = labelledBy.split(/\\s+/).filter(Boolean).map((id) => document.getElementById(id)?.textContent || "");
+          const text = normalizeWhitespace(parts.join(" "));
+          if (text) return text;
+        }
+        if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+          if (el.id) {
+            const label = document.querySelector("label[for="" + cssEscape(el.id) + ""]");
+            if (label) {
+              const text = normalizeWhitespace(label.textContent || "");
+              if (text) return text;
+            }
+          }
+          const wrap = el.closest("label");
+          if (wrap) {
+            const text = normalizeWhitespace(wrap.textContent || "");
+            if (text) return text;
+          }
+        }
+        if (el instanceof HTMLImageElement) {
+          return normalizeWhitespace(el.getAttribute("alt") || el.getAttribute("title") || "");
+        }
+        return normalizeWhitespace(el.getAttribute("title") || "");
+      };
+      const getImplicitRole = (el) => {
+        if (!el || !(el instanceof Element)) return "";
+        const explicitRole = (el.getAttribute("role") || "").trim().split(/\\s+/)[0];
+        if (explicitRole) return explicitRole;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "button") return "button";
+        if (tag === "summary") return "button";
+        if (tag === "a" && el.hasAttribute("href")) return "link";
+        if (tag === "input") {
+          const type = (el.getAttribute("type") || "text").toLowerCase();
+          if (type === "checkbox") return "checkbox";
+          if (type === "radio") return "radio";
+          if (type === "range") return "slider";
+          if (type === "submit" || type === "button" || type === "reset") return "button";
+          if (type === "file") return "button";
+          return "textbox";
+        }
+        if (tag === "textarea") return "textbox";
+        if (tag === "select") return "combobox";
+        if (tag === "img") return "img";
+        if (tag === "ul" || tag === "ol") return "list";
+        if (tag === "li") return "listitem";
+        if (tag === "table") return "table";
+        if (tag === "tr") return "row";
+        if (tag === "td") return "cell";
+        if (tag === "th") return "columnheader";
+        if (/^h[1-6]$/.test(tag)) return "heading";
+        if (tag === "option") return "option";
+        if (tag === "fieldset") return "group";
+        if (tag === "form") return "form";
+        if (el.hasAttribute("contenteditable")) return "textbox";
+        return explicitRole;
+      };
+      const matchText = (actual, expected, exact) => {
+        const normalizedActual = normalizeWhitespace(actual);
+        if (expected && expected.kind === "regex") {
+          const regex = new RegExp(expected.source, expected.flags);
+          return regex.test(normalizedActual);
+        }
+        const normalizedExpected = normalizeWhitespace(expected.value);
+        if (exact) {
+          return normalizedActual === normalizedExpected;
+        }
+        return normalizedActual.toLowerCase().includes(normalizedExpected.toLowerCase());
+      };
+      const matchName = (actual, expected, exact) => {
+        const normalizedActual = normalizeWhitespace(actual);
+        if (expected && expected.kind === "regex") {
+          const regex = new RegExp(expected.source, expected.flags);
+          return regex.test(normalizedActual);
+        }
+        const normalizedExpected = normalizeWhitespace(expected.value);
+        if (exact) {
+          return normalizedActual === normalizedExpected;
+        }
+        return normalizedActual.toLowerCase().includes(normalizedExpected.toLowerCase());
+      };
+      const query = ${serializedQuery};
+      const nodes = Array.from(querySelectorAllDeep(document, "*"));
+      const selectorMatches = () => {
+        if (query.kind !== "selector") {
+          return [];
+        }
+        if (query.selector.includes(">>>")) {
+          return querySelectorAllDeep(document, query.selector);
+        }
+        if (query.parsed?.type === "xpath") {
+          const result = document.evaluate(query.parsed.value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+          const list = [];
+          for (let i = 0; i < result.snapshotLength; i += 1) {
+            const item = result.snapshotItem(i);
+            if (item instanceof Element) {
+              list.push(item);
+            }
+          }
+          return list;
+        }
+        return Array.from(document.querySelectorAll(query.selector));
+      };
+      const selectorMatchSet = selectorMatches();
+      const matches = nodes.filter((el) => {
+        if (!(el instanceof Element)) return false;
+        if (query.kind === "selector") {
+          return selectorMatchSet.includes(el);
+        }
+        if (query.kind === "text") {
+          const text = textFromElement(el);
+          return matchText(text, query.text, Boolean(query.options?.exact));
+        }
+        const role = getImplicitRole(el);
+        if (!role || role !== query.role) {
+          return false;
+        }
+        if (!query.options?.includeHidden && isHidden(el)) {
+          return false;
+        }
+        if (query.options?.name == null) {
+          return true;
+        }
+        const name = getLabelText(el) || textFromElement(el);
+        return matchName(name, query.options.name, Boolean(query.options?.exact));
+      });
+      const textMatches = query.kind === "text"
+        ? matches.filter((el) => !matches.some((other) => other !== el && el.contains(other)))
+        : matches;
+      const elements = ${all ? "textMatches" : "textMatches.slice(0, 1)"};
+      const el = elements[0] || null;
+      ${body}
+    })()`;
+  }
+  serializeLocatorQuery(query) {
+    switch (query.kind) {
+      case "selector":
+        return JSON.stringify({ kind: "selector", selector: query.selector, options: query.options, parsed: parseSelector(query.selector) });
+      case "text":
+        return JSON.stringify({
+          kind: "text",
+          text: this.serializeTextQuery(query.text),
+          options: query.options
+        });
+      case "role":
+        return JSON.stringify({
+          kind: "role",
+          role: query.role,
+          options: query.options ? {
+            ...query.options,
+            name: query.options.name != null ? this.serializeTextQuery(query.options.name) : void 0
+          } : void 0
+        });
+    }
+  }
+  serializeTextQuery(text) {
+    if (text instanceof RegExp) {
+      return { kind: "regex", source: text.source, flags: text.flags.replace("g", "") };
+    }
+    return { kind: "string", value: text };
+  }
   async performClick(selector, options, isDouble) {
     const start = Date.now();
     const actionName = isDouble ? "dblclick" : "click";
@@ -1380,7 +1866,13 @@ var Page = class {
     return null;
   }
   locator(selector) {
-    return new Locator(this.mainFrame(), selector);
+    return this.mainFrame().locator(selector);
+  }
+  getByText(text, options = {}) {
+    return this.mainFrame().getByText(text, options);
+  }
+  getByRole(role, options = {}) {
+    return this.mainFrame().getByRole(role, options);
   }
   async goto(url, options = {}) {
     ensureAllowedUrl(url, { allowFileUrl: options.allowFileUrl });
@@ -2253,42 +2745,42 @@ var AssertionError = class extends Error {
 
 // src/assert/expect.ts
 var ElementExpectation = class _ElementExpectation {
-  frame;
-  selector;
+  target;
   options;
   negate;
   events;
-  constructor(frame, selector, options, negate, events) {
-    this.frame = frame;
-    this.selector = selector;
+  constructor(target, options, negate, events) {
+    this.target = target;
     this.options = options;
     this.negate = negate;
     this.events = events;
   }
   get not() {
-    return new _ElementExpectation(this.frame, this.selector, this.options, !this.negate, this.events);
+    return new _ElementExpectation(this.target, this.options, !this.negate, this.events);
   }
   async toExist() {
     return this.assert(async () => {
-      const exists = await this.frame.exists(this.selector, this.options);
+      const exists = await this.target.exists();
       return this.negate ? !exists : exists;
     }, this.negate ? "Expected element not to exist" : "Expected element to exist");
   }
   async toBeVisible() {
     return this.assert(async () => {
-      const visible = await this.frame.isVisible(this.selector, this.options);
+      const visible = await this.target.isVisible();
+      if (visible == null) return this.negate ? true : false;
       return this.negate ? !visible : visible;
     }, this.negate ? "Expected element not to be visible" : "Expected element to be visible");
   }
   async toBeHidden() {
     return this.assert(async () => {
-      const visible = await this.frame.isVisible(this.selector, this.options);
+      const visible = await this.target.isVisible();
+      if (visible == null) return this.negate ? true : false;
       return this.negate ? visible : !visible;
     }, this.negate ? "Expected element not to be hidden" : "Expected element to be hidden");
   }
   async toBeEnabled() {
     return this.assert(async () => {
-      const enabled = await this.frame.isEnabled(this.selector, this.options);
+      const enabled = await this.target.isEnabled();
       if (enabled == null) {
         return this.negate ? true : false;
       }
@@ -2297,7 +2789,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeDisabled() {
     return this.assert(async () => {
-      const enabled = await this.frame.isEnabled(this.selector, this.options);
+      const enabled = await this.target.isEnabled();
       if (enabled == null) {
         return this.negate ? true : false;
       }
@@ -2307,7 +2799,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeChecked() {
     return this.assert(async () => {
-      const checked = await this.frame.isChecked(this.selector, this.options);
+      const checked = await this.target.isChecked();
       if (checked == null) {
         return this.negate ? true : false;
       }
@@ -2316,7 +2808,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeUnchecked() {
     return this.assert(async () => {
-      const checked = await this.frame.isChecked(this.selector, this.options);
+      const checked = await this.target.isChecked();
       if (checked == null) {
         return this.negate ? true : false;
       }
@@ -2327,7 +2819,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveText(textOrRegex) {
     const expected = textOrRegex;
     return this.assert(async () => {
-      const text = await this.frame.text(this.selector, this.options);
+      const text = await this.target.text();
       if (text == null) {
         return this.negate ? true : false;
       }
@@ -2338,7 +2830,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveExactText(textOrRegex) {
     const expected = textOrRegex;
     return this.assert(async () => {
-      const text = await this.frame.text(this.selector, this.options);
+      const text = await this.target.text();
       if (text == null) {
         return this.negate ? true : false;
       }
@@ -2349,7 +2841,7 @@ var ElementExpectation = class _ElementExpectation {
   async toContainText(textOrRegex) {
     const expected = textOrRegex;
     return this.assert(async () => {
-      const text = await this.frame.text(this.selector, this.options);
+      const text = await this.target.text();
       if (text == null) {
         return this.negate ? true : false;
       }
@@ -2360,7 +2852,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveValue(valueOrRegex) {
     const expected = valueOrRegex;
     return this.assert(async () => {
-      const value = await this.frame.value(this.selector, this.options);
+      const value = await this.target.value();
       if (value == null) {
         return this.negate ? true : false;
       }
@@ -2371,7 +2863,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveAttribute(name, valueOrRegex) {
     const expected = valueOrRegex;
     return this.assert(async () => {
-      const value = await this.frame.attribute(this.selector, name, this.options);
+      const value = await this.target.attribute(name);
       if (expected === void 0) {
         const exists = value != null;
         return this.negate ? !exists : exists;
@@ -2391,7 +2883,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toHaveCount(expected) {
     return this.assert(async () => {
-      const count = await this.frame.count(this.selector, this.options);
+      const count = await this.target.count();
       const matches = count === expected;
       return this.negate ? !matches : matches;
     }, this.negate ? "Expected element count not to match" : "Expected element count to match", { expected });
@@ -2399,7 +2891,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveClass(nameOrRegex) {
     const expected = nameOrRegex;
     return this.assert(async () => {
-      const classes = await this.frame.classes(this.selector, this.options);
+      const classes = await this.target.classes();
       if (classes == null) {
         return this.negate ? true : false;
       }
@@ -2409,7 +2901,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toHaveClasses(expected) {
     return this.assert(async () => {
-      const classes = await this.frame.classes(this.selector, this.options);
+      const classes = await this.target.classes();
       if (classes == null) {
         return this.negate ? true : false;
       }
@@ -2420,7 +2912,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveCss(property, valueOrRegex) {
     const expected = valueOrRegex;
     return this.assert(async () => {
-      const value = await this.frame.css(this.selector, property, this.options);
+      const value = await this.target.css(property);
       if (value == null) {
         return this.negate ? true : false;
       }
@@ -2431,7 +2923,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toHaveFocus() {
     return this.assert(async () => {
-      const focused = await this.frame.hasFocus(this.selector, this.options);
+      const focused = await this.target.hasFocus();
       if (focused == null) {
         return this.negate ? true : false;
       }
@@ -2440,7 +2932,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeInViewport(options = {}) {
     return this.assert(async () => {
-      const inViewport = await this.frame.isInViewport(this.selector, this.options, Boolean(options.fully));
+      const inViewport = await this.target.isInViewport(Boolean(options.fully));
       if (inViewport == null) {
         return this.negate ? true : false;
       }
@@ -2449,7 +2941,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeEditable() {
     return this.assert(async () => {
-      const editable = await this.frame.isEditable(this.selector, this.options);
+      const editable = await this.target.isEditable();
       if (editable == null) {
         return this.negate ? true : false;
       }
@@ -2459,7 +2951,7 @@ var ElementExpectation = class _ElementExpectation {
   async assert(predicate, message, details = {}) {
     const timeoutMs = this.options.timeoutMs ?? 3e4;
     const start = Date.now();
-    this.events.emit("assertion:start", { name: message, selector: this.selector, frameId: this.frame.id });
+    this.events.emit("assertion:start", { name: message, selector: this.target.label, frameId: this.target.frameId });
     let lastState;
     try {
       await waitFor(async () => {
@@ -2469,13 +2961,51 @@ var ElementExpectation = class _ElementExpectation {
       }, { timeoutMs, description: message });
     } catch {
       const duration2 = Date.now() - start;
-      this.events.emit("assertion:end", { name: message, selector: this.selector, frameId: this.frame.id, durationMs: duration2, status: "failed" });
-      throw new AssertionError(message, { selector: this.selector, timeoutMs, lastState: { lastState, ...details } });
+      this.events.emit("assertion:end", { name: message, selector: this.target.label, frameId: this.target.frameId, durationMs: duration2, status: "failed" });
+      throw new AssertionError(message, { selector: this.target.label, timeoutMs, lastState: { lastState, ...details } });
     }
     const duration = Date.now() - start;
-    this.events.emit("assertion:end", { name: message, selector: this.selector, frameId: this.frame.id, durationMs: duration, status: "passed" });
+    this.events.emit("assertion:end", { name: message, selector: this.target.label, frameId: this.target.frameId, durationMs: duration, status: "passed" });
   }
 };
+function frameTarget(frame, selector, options) {
+  return {
+    label: selector,
+    frameId: frame.id,
+    exists: () => frame.exists(selector, options),
+    isVisible: () => frame.isVisible(selector, options),
+    isEnabled: () => frame.isEnabled(selector, options),
+    isChecked: () => frame.isChecked(selector, options),
+    text: () => frame.text(selector, options),
+    value: () => frame.value(selector, options),
+    attribute: (name) => frame.attribute(selector, name, options),
+    count: () => frame.count(selector, options),
+    classes: () => frame.classes(selector, options),
+    css: (property) => frame.css(selector, property, options),
+    hasFocus: () => frame.hasFocus(selector, options),
+    isInViewport: (fully = false) => frame.isInViewport(selector, options, fully),
+    isEditable: () => frame.isEditable(selector, options)
+  };
+}
+function locatorTarget(locator) {
+  return {
+    label: locator.describe(),
+    frameId: locator.getFrameId(),
+    exists: () => locator.exists(),
+    isVisible: () => locator.isVisible(),
+    isEnabled: () => locator.isEnabled(),
+    isChecked: () => locator.isChecked(),
+    text: () => locator.text(),
+    value: () => locator.value(),
+    attribute: (name) => locator.attribute(name),
+    count: () => locator.count(),
+    classes: () => locator.classes(),
+    css: (property) => locator.css(property),
+    hasFocus: () => locator.hasFocus(),
+    isInViewport: (fully = false) => locator.isInViewport(fully),
+    isEditable: () => locator.isEditable()
+  };
+}
 var ExpectFrame = class {
   frame;
   events;
@@ -2484,25 +3014,31 @@ var ExpectFrame = class {
     this.events = events;
   }
   element(selector, options = {}) {
-    return new ElementExpectation(this.frame, selector, options, false, this.events);
+    return new ElementExpectation(frameTarget(this.frame, selector, options), options, false, this.events);
   }
 };
-function expect(page) {
+function expect(target) {
+  if (target instanceof Locator) {
+    return new ElementExpectation(locatorTarget(target), {}, false, target.getEvents());
+  }
   return {
-    element: (selector, options = {}) => new ElementExpectation(page.mainFrame(), selector, options, false, page.getEvents()),
+    element: (selector, options = {}) => new ElementExpectation(frameTarget(target.mainFrame(), selector, options), options, false, target.getEvents()),
     frame: (options) => {
-      const frame = page.frame(options);
+      const frame = target.frame(options);
       if (!frame) {
         throw new AssertionError("Frame not found", { selector: JSON.stringify(options) });
       }
-      return new ExpectFrame(frame, page.getEvents());
+      return new ExpectFrame(frame, target.getEvents());
     }
   };
 }
-Page.prototype.expect = function(selector, options) {
+Page.prototype.expect = function(target, options) {
   const builder = expect(this);
-  if (selector) {
-    return builder.element(selector, options);
+  if (target instanceof Locator) {
+    return expect(target);
+  }
+  if (target) {
+    return builder.element(target, options);
   }
   return builder;
 };
@@ -2588,36 +3124,28 @@ function printHelp() {
   console.log(`cdpwright (cpw) \u2014 Chromium automation CLI
 
 Commands:
+  screenshot <url> -o f    Take a screenshot (PNG/JPEG)
+  pdf <url> -o file.pdf    Generate visual PDF of page
+  html <url> -o file.html  Save the page HTML source
+  eval <url> <script>      Run JS in page, print result as JSON
   download [options]       Download pinned Chromium snapshot
   install                  Alias for download
-  open <url>               Launch browser session and navigate to URL
-  close                    Close the running browser session
-  screenshot [url] -o f    Take a screenshot (PNG/JPEG)
-  html [url] -o file.html  Save the page HTML source
-  pdf [url] -o file.pdf    Generate PDF of page (headless only)
-  eval [url] <script>      Run script in page, print result as JSON
   version                  Print cdpwright and Chromium versions
 
-Session:
-  'open' starts a browser and saves a session. Other commands auto-connect
-  to the running session when no URL is given. 'close' shuts it down.
-
-Download options:
-  --latest                 Download the latest Chromium revision
-  --mirror <url>           Custom mirror base URL
-  --url <url>              Exact zip URL override
-
-Common options:
+Options:
   --headless               Run in headless mode (default for screenshot, pdf, eval)
-  --headed                 Run in headed mode (default for open)
-
-Screenshot options:
-  -o, --output <file>      Output file path (required)
-  --full-page              Capture full scrollable page
+  --headed                 Run in headed mode
+  -o, --output <file>      Output file path (for screenshot, html, pdf)
+  --full-page              Capture full scrollable page (for screenshot)
+  --latest                 Download the latest Chromium revision (for download)
+  --mirror <url>           Custom mirror base URL (for download)
+  --url <url>              Exact zip URL override (for download)
 
-PDF options:
-  -o, --output <file>      Output file path (required)
-  Note: pdf always runs headless (CDP limitation)`);
+Interactive session:
+  open <url>               Open browser and start a session
+  close                    Close the running session
+  When a session is running, commands accept no URL and operate on the
+  live page instead:  cpw screenshot -o shot.png | cpw eval "document.title"`);
 }
 function hasFlag(args, flag) {
   return args.includes(flag);