feat: locator descendants (#171)

* feat(locator): Add locator(), $() and $$() methods to select descendants

* chore: Update std import in showcase.tsx

* chore: Exclude docs folder from lint checks

Author: adamgreg

deno.jsonc

@@ -36,5 +36,8 @@
       "docs/static/icon.png",
       "bindings/celestial.ts"
     ]
+  },
+  "lint": {
+    "exclude": ["docs"]
   }
 }

docs/pages/showcase.tsx

@@ -1,6 +1,6 @@
 import { launch } from "../../mod.ts";
 import type { PageProps } from "https://deno.land/x/pyro@0.6.1/page.ts";
-import { ensureFileSync } from "https://deno.land/std@0.215.0/fs/ensure_file.ts";
+import { ensureFileSync } from "@std/fs/ensure-file";
 
 export const config = {
   title: "Showcase",

src/locator.ts

@@ -69,4 +69,37 @@ export class Locator<T> {
   async wait(): Promise<ElementHandle> {
     return await this.#page.waitForSelector(this.#selector);
   }
+
+  /** Creates a derived Locator for a descendant element. */
+  locator<T>(selector: string): Locator<T> {
+    return new Locator(
+      this.#page,
+      `${this.#selector} ${selector}`,
+      this.#timeout,
+    );
+  }
+
+  /**
+   * Queries the locator for an element matching the given selector.
+   *
+   * @example
+   * ```ts
+   * const elementWithClass = await locator.$(".class");
+   * ```
+   */
+  $(selector: string): Promise<ElementHandle | null> {
+    return this.#runLocator((handle) => handle.$(selector));
+  }
+
+  /**
+   * Queries the locator for all elements matching the given selector.
+   *
+   * @example
+   * ```ts
+   * const elementsWithClass = await locator.$$(".class");
+   * ```
+   */
+  $$(selector: string): Promise<ElementHandle[]> {
+    return this.#runLocator((handle) => handle.$$(selector));
+  }
 }

tests/locator_test.ts

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import { assertEquals } from "@std/assert";
+import { assertEquals, assertExists } from "@std/assert";
 import { launch } from "../mod.ts";
 import * as path from "@std/path";
 
@@ -101,3 +101,50 @@ Deno.test("Locator - fill()", async () => {
   await page.close();
   await browser.close();
 });
+
+Deno.test("Locator - locator()", async () => {
+  await using server = await serveFixture("fixtures/wait_for_element.html");
+
+  await using browser = await launch();
+  await using page = await browser.newPage(server.address);
+  const targetLocator = page.locator<HTMLDivElement>("#target");
+
+  const h1Locator = targetLocator.locator<HTMLHeadingElement>("h1");
+
+  const res = await h1Locator.evaluate((el) => {
+    return document.querySelector("h1") === el;
+  });
+  assertEquals(res, true);
+});
+
+Deno.test("Locator - $()", async () => {
+  await using server = await serveFixture("fixtures/wait_for_element.html");
+
+  await using browser = await launch();
+  await using page = await browser.newPage(server.address);
+  const targetLocator = page.locator<HTMLDivElement>("#target");
+
+  const h1El = await targetLocator.$("h1");
+  assertExists(h1El);
+
+  const res = await h1El.evaluate((el) => {
+    return document.querySelector("h1") === el;
+  });
+  assertEquals(res, true);
+});
+
+Deno.test("Locator - $$()", async () => {
+  await using server = await serveFixture("fixtures/wait_for_element.html");
+
+  await using browser = await launch();
+  await using page = await browser.newPage(server.address);
+  const targetLocator = page.locator<HTMLDivElement>("#target");
+
+  const children = await targetLocator.$$("h1");
+  assertEquals(children.length, 1);
+
+  const res = await children[0].evaluate((el) => {
+    return document.querySelector("h1") === el;
+  });
+  assertEquals(res, true);
+});