@zerolith/test 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -19,14 +19,20 @@ it("renders and hydrates", async () =>
 });
 ```
 
-- `mount` renders a view into a container attached to the document and remembers it; `cleanup` disposes everything mounted, in reverse order.
+- `mount` renders a view into a container attached to the document and remembers it; given a function, as in `mount(() => Dashboard())`, it calls it inside an owner of its own, so a component that registers cleanups with `onDispose` mounts as it is. `cleanup` disposes everything mounted, in reverse order.
 - `settle` waits for the promises a test started, such as resources and lazy routes; effects themselves run synchronously.
 - `hydrationMismatches` renders a view with the server renderer, hydrates the same view over that markup, and returns every disagreement, so a component that cannot hydrate fails its test.
 - `accessibilityIssues` finds the defects a test can catch without a browser engine's accessibility tree: images without alternative text, controls without a label, buttons and links without a name, frames without a title.
 
-The guide is `docs/guide/testing.md` in the repository.
+Under Vitest, which reads the components itself, add the plugin from `@zerolith/vite` as `zerolith({ hot: false })` so a test reads JSX and stylesheets imported with `?scoped` as the app does; a project from `zerolith new` has it in `vitest.config.ts`. The guide is on the [docs site](https://zerolith.dev/guide/testing/).
 
-Status: pre-alpha, nothing published.
+Status: alpha. Install with `npm install --save-dev @zerolith/test@alpha`; the API may change before 1.0.
+
+## Documentation
+
+- The [testing guide](https://zerolith.dev/guide/testing/) explains it with examples that run as tests.
+- The [reference](https://zerolith.dev/reference/zerolith-test/) lists every export, generated from the source.
+- New to zerolith? The [tutorial](https://zerolith.dev/learn/) builds an app step by step, and the [playground](https://zerolith.dev/playground/) runs code in the browser.
 
 ## License
 

package/dist/index.d.ts

@@ -4,11 +4,12 @@
  * a view's server markup against hydration, and find the accessibility
  * defects a test can catch.
  */
-import { type HydrationMismatch, type Root } from "zerolith";
+import { type HydrationMismatch, type Renderable, type Root } from "zerolith";
 /** What `mount` returns. */
 export interface Mounted {
     /** The element the view was rendered into. */
     readonly container: HTMLElement;
+    /** The root `render` returned for the view; `unmount` disposes it. */
     readonly root: Root;
     /** Disposes the view and removes the container; `cleanup` does the same for every mount. */
     unmount(): void;
@@ -17,30 +18,45 @@ export interface Mounted {
 export interface MountOptions {
     /** Renders into this element instead of a new `div`. */
     container?: HTMLElement;
-    /** Appends a new container to `document.body`. Defaults to true; layout and focus need it. */
+    /** Appends a new container to `document.body`. Defaults to true; layout and focus need it. Ignored with `container`. */
     attach?: boolean;
 }
-/** Renders a view into a container and remembers it for `cleanup`. */
-export declare function mount(view: unknown, options?: MountOptions): Mounted;
-/** Unmounts everything `mount` created, newest first. Register it as the runner's after-each hook. */
+/**
+ * Renders a view into a container and remembers it for `cleanup`. Given a
+ * function that returns the view, as `mount(() => Page())`, it hands the
+ * function to `render`, which calls it inside the root's owner, so a
+ * component that registers cleanups with `onDispose` mounts as it is, and
+ * its cleanups run when the view is unmounted. A component that takes
+ * props, passed uncalled, fails with `mount_component_uncalled`, as
+ * `render` does. A container `mount` created is removed even when
+ * rendering throws.
+ */
+export declare function mount(view: Renderable | (() => Renderable), options?: MountOptions): Mounted;
+/** Unmounts everything `mount` created, newest first, each even when another's cleanup throws, and then throws the first error. Register it as the runner's after-each hook. */
 export declare function cleanup(): void;
 /**
- * Waits for the asynchronous work a test started: resources, lazy routes,
- * and anything scheduled with promises or a timer of zero. Effects run
- * synchronously when a signal changes, so they need no settling.
+ * Waits `rounds` turns of the timer queue, two by default: enough for
+ * promise chains, a resource whose loader resolves at once, and zero-delay
+ * timers. Effects run synchronously when a signal changes, so they need no
+ * settling. For a module import or a request, wait on its result with the
+ * runner's `waitFor` instead.
  */
 export declare function settle(rounds?: number): Promise<void>;
 /**
- * Renders `view()` with the server renderer, hydrates a second `view()` over
- * that markup, and returns every disagreement. An empty array means the
- * component hydrates cleanly; the container is discarded afterwards.
+ * Renders `view` with the server renderer, hydrates it over that markup,
+ * and returns every disagreement. Each pass calls `view` inside its own
+ * owner, so the effects and `onDispose` cleanups a component registers end
+ * before the helper returns. An empty array means the component hydrates
+ * cleanly; the container is discarded afterwards.
  */
-export declare function hydrationMismatches(view: () => unknown): HydrationMismatch[];
+export declare function hydrationMismatches(view: () => Renderable): HydrationMismatch[];
 /** The accessibility checks `accessibilityIssues` runs. */
 export type AccessibilityCode = "image_without_alt" | "control_without_label" | "button_without_name" | "link_without_name" | "frame_without_title";
 /** One defect found by `accessibilityIssues`. */
 export interface AccessibilityIssue {
+    /** Which check the element failed, such as `image_without_alt`. */
     readonly code: AccessibilityCode;
+    /** The element that failed the check, found inside the container passed to `accessibilityIssues`. */
     readonly element: Element;
 }
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,IAAI,EAAmB,MAAM,UAAU,CAAC;AAG9E,4BAA4B;AAC5B,MAAM,WAAW,OAAO;IAEpB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IAEzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAID,sEAAsE;AACtE,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CA2BxE;AAED,sGAAsG;AACtG,wBAAgB,OAAO,IAAI,IAAI,CAM9B;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAQ5E;AAED,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG,uBAAuB,GAAG,qBAAqB,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAEpJ,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IAE/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC7B;AA0BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,UAAU,GAAG,kBAAkB,EAAE,CAqC/E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAmB,MAAM,UAAU,CAAC;AAG/F,4BAA4B;AAC5B,MAAM,WAAW,OAAO;IAEpB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IAEzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,wHAAwH;IACxH,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAID;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CA6ChG;AAED,gLAAgL;AAChL,wBAAgB,OAAO,IAAI,IAAI,CAkB9B;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAQ/E;AAED,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG,uBAAuB,GAAG,qBAAqB,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAEpJ,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IAE/B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC7B;AA8CD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,UAAU,GAAG,kBAAkB,EAAE,CAqC/E"}

package/dist/index.js

@@ -7,13 +7,31 @@
 import { hydrate, render } from "zerolith";
 import { renderToString } from "zerolith/ssr";
 const mounted = [];
-/** Renders a view into a container and remembers it for `cleanup`. */
+/**
+ * Renders a view into a container and remembers it for `cleanup`. Given a
+ * function that returns the view, as `mount(() => Page())`, it hands the
+ * function to `render`, which calls it inside the root's owner, so a
+ * component that registers cleanups with `onDispose` mounts as it is, and
+ * its cleanups run when the view is unmounted. A component that takes
+ * props, passed uncalled, fails with `mount_component_uncalled`, as
+ * `render` does. A container `mount` created is removed even when
+ * rendering throws.
+ */
 export function mount(view, options = {}) {
     const container = options.container ?? document.createElement("div");
     if (options.container === undefined && options.attach !== false) {
         document.body.append(container);
     }
-    const root = render(view, container);
+    let root;
+    try {
+        root = render(view, container);
+    }
+    catch (error) {
+        if (options.container === undefined) {
+            container.remove();
+        }
+        throw error;
+    }
     const entry = {
         container,
         root,
@@ -22,25 +40,40 @@ export function mount(view, options = {}) {
             if (index !== -1) {
                 mounted.splice(index, 1);
             }
-            root.dispose();
-            if (options.container === undefined) {
-                container.remove();
+            try {
+                root.dispose();
+            }
+            finally {
+                if (options.container === undefined) {
+                    container.remove();
+                }
             }
         }
     };
     mounted.push(entry);
     return entry;
 }
-/** Unmounts everything `mount` created, newest first. Register it as the runner's after-each hook. */
+/** Unmounts everything `mount` created, newest first, each even when another's cleanup throws, and then throws the first error. Register it as the runner's after-each hook. */
 export function cleanup() {
+    const errors = [];
     for (const entry of mounted.toReversed()) {
-        entry.unmount();
+        try {
+            entry.unmount();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0) {
+        throw errors[0];
     }
 }
 /**
- * Waits for the asynchronous work a test started: resources, lazy routes,
- * and anything scheduled with promises or a timer of zero. Effects run
- * synchronously when a signal changes, so they need no settling.
+ * Waits `rounds` turns of the timer queue, two by default: enough for
+ * promise chains, a resource whose loader resolves at once, and zero-delay
+ * timers. Effects run synchronously when a signal changes, so they need no
+ * settling. For a module import or a request, wait on its result with the
+ * runner's `waitFor` instead.
  */
 export function settle(rounds = 2) {
     let chain = Promise.resolve();
@@ -50,34 +83,50 @@ export function settle(rounds = 2) {
     return chain;
 }
 /**
- * Renders `view()` with the server renderer, hydrates a second `view()` over
- * that markup, and returns every disagreement. An empty array means the
- * component hydrates cleanly; the container is discarded afterwards.
+ * Renders `view` with the server renderer, hydrates it over that markup,
+ * and returns every disagreement. Each pass calls `view` inside its own
+ * owner, so the effects and `onDispose` cleanups a component registers end
+ * before the helper returns. An empty array means the component hydrates
+ * cleanly; the container is discarded afterwards.
  */
 export function hydrationMismatches(view) {
     const container = document.createElement("div");
-    container.innerHTML = renderToString(view());
-    const result = hydrate(view(), container);
+    container.innerHTML = renderToString(view);
+    const result = hydrate(view, container);
     const mismatches = [...result.mismatches];
     result.dispose();
     return mismatches;
 }
-function hasName(element) {
-    const label = element.getAttribute("aria-label") ?? "";
-    if (label.trim() !== "" || element.hasAttribute("aria-labelledby") || (element.getAttribute("title") ?? "").trim() !== "") {
-        return true;
+/** True when an element has an accessible name from an attribute: `aria-label`, `aria-labelledby`, or `title`. */
+function namedByAttribute(element) {
+    return (element.getAttribute("aria-label") ?? "").trim() !== "" || element.hasAttribute("aria-labelledby") || (element.getAttribute("title") ?? "").trim() !== "";
+}
+/** The text an element shows to assistive technology: its text content, leaving out every `aria-hidden="true"` subtree. */
+function exposedText(element) {
+    let text = "";
+    for (const node of element.childNodes) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            text += node.textContent ?? "";
+        }
+        else if (node instanceof Element && node.getAttribute("aria-hidden") !== "true") {
+            text += exposedText(node);
+        }
     }
-    if ((element.textContent ?? "").trim() !== "") {
+    return text;
+}
+function hasName(element) {
+    if (namedByAttribute(element) || exposedText(element).trim() !== "") {
         return true;
     }
-    return [...element.querySelectorAll("img[alt]")].some((image) => (image.getAttribute("alt") ?? "").trim() !== "");
+    return [...element.querySelectorAll("img[alt]")].some((image) => (image.getAttribute("alt") ?? "").trim() !== "" && image.closest("[aria-hidden=\"true\"]") === null);
 }
 function isLabeled(control) {
     if (hasName(control) || control.closest("label") !== null) {
         return true;
     }
     const id = control.getAttribute("id");
-    return id !== null && id !== "" && control.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`) !== null;
+    const tree = control.getRootNode();
+    return id !== null && id !== "" && [...tree.querySelectorAll("label[for]")].some((label) => label.htmlFor === id);
 }
 /**
  * Finds the defects that need no accessibility tree to detect, the ones the
@@ -107,7 +156,7 @@ export function accessibilityIssues(container) {
         }
     }
     for (const frame of container.querySelectorAll("iframe")) {
-        if ((frame.getAttribute("title") ?? "").trim() === "") {
+        if (!namedByAttribute(frame)) {
             issues.push({ code: "frame_without_title", element: frame });
         }
     }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@zerolith/test",
-    "version": "0.1.0-alpha.1",
+    "version": "0.1.0-alpha.10",
     "description": "Test helpers for zerolith: mount views with automatic cleanup, settle async work, check a view's server markup against hydration, and find the accessibility defects a test can catch",
     "license": "Apache-2.0",
     "author": "molexxxx",
-    "homepage": "https://github.com/molexxxx/zerolith#readme",
+    "homepage": "https://zerolith.dev/",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/molexxxx/zerolith.git",
@@ -41,9 +41,9 @@
         "build": "tsc -p tsconfig.build.json"
     },
     "peerDependencies": {
-        "zerolith": "^0.1.0-alpha.1"
+        "zerolith": "^0.1.0-alpha.10"
     },
     "devDependencies": {
-        "zerolith": "^0.1.0-alpha.1"
+        "zerolith": "^0.1.0-alpha.10"
     }
 }

package/src/index.ts

@@ -4,7 +4,7 @@
  * a view's server markup against hydration, and find the accessibility
  * defects a test can catch.
  */
-import { type HydrationMismatch, type Root, hydrate, render } from "zerolith";
+import { type HydrationMismatch, type Renderable, type Root, hydrate, render } from "zerolith";
 import { renderToString } from "zerolith/ssr";
 
 /** What `mount` returns. */
@@ -12,6 +12,7 @@ export interface Mounted
 {
     /** The element the view was rendered into. */
     readonly container: HTMLElement;
+    /** The root `render` returned for the view; `unmount` disposes it. */
     readonly root: Root;
     /** Disposes the view and removes the container; `cleanup` does the same for every mount. */
     unmount(): void;
@@ -22,21 +23,42 @@ export interface MountOptions
 {
     /** Renders into this element instead of a new `div`. */
     container?: HTMLElement;
-    /** Appends a new container to `document.body`. Defaults to true; layout and focus need it. */
+    /** Appends a new container to `document.body`. Defaults to true; layout and focus need it. Ignored with `container`. */
     attach?: boolean;
 }
 
 const mounted: Mounted[] = [];
 
-/** Renders a view into a container and remembers it for `cleanup`. */
-export function mount(view: unknown, options: MountOptions = {}): Mounted
+/**
+ * Renders a view into a container and remembers it for `cleanup`. Given a
+ * function that returns the view, as `mount(() => Page())`, it hands the
+ * function to `render`, which calls it inside the root's owner, so a
+ * component that registers cleanups with `onDispose` mounts as it is, and
+ * its cleanups run when the view is unmounted. A component that takes
+ * props, passed uncalled, fails with `mount_component_uncalled`, as
+ * `render` does. A container `mount` created is removed even when
+ * rendering throws.
+ */
+export function mount(view: Renderable | (() => Renderable), options: MountOptions = {}): Mounted
 {
     const container = options.container ?? document.createElement("div");
     if (options.container === undefined && options.attach !== false)
     {
         document.body.append(container);
     }
-    const root = render(view, container);
+    let root: Root;
+    try
+    {
+        root = render(view, container);
+    }
+    catch (error)
+    {
+        if (options.container === undefined)
+        {
+            container.remove();
+        }
+        throw error;
+    }
     const entry: Mounted = {
         container,
         root,
@@ -47,10 +69,16 @@ export function mount(view: unknown, options: MountOptions = {}): Mounted
             {
                 mounted.splice(index, 1);
             }
-            root.dispose();
-            if (options.container === undefined)
+            try
             {
-                container.remove();
+                root.dispose();
+            }
+            finally
+            {
+                if (options.container === undefined)
+                {
+                    container.remove();
+                }
             }
         }
     };
@@ -58,19 +86,33 @@ export function mount(view: unknown, options: MountOptions = {}): Mounted
     return entry;
 }
 
-/** Unmounts everything `mount` created, newest first. Register it as the runner's after-each hook. */
+/** Unmounts everything `mount` created, newest first, each even when another's cleanup throws, and then throws the first error. Register it as the runner's after-each hook. */
 export function cleanup(): void
 {
+    const errors: unknown[] = [];
     for (const entry of mounted.toReversed())
     {
-        entry.unmount();
+        try
+        {
+            entry.unmount();
+        }
+        catch (error)
+        {
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0)
+    {
+        throw errors[0];
     }
 }
 
 /**
- * Waits for the asynchronous work a test started: resources, lazy routes,
- * and anything scheduled with promises or a timer of zero. Effects run
- * synchronously when a signal changes, so they need no settling.
+ * Waits `rounds` turns of the timer queue, two by default: enough for
+ * promise chains, a resource whose loader resolves at once, and zero-delay
+ * timers. Effects run synchronously when a signal changes, so they need no
+ * settling. For a module import or a request, wait on its result with the
+ * runner's `waitFor` instead.
  */
 export function settle(rounds = 2): Promise<void>
 {
@@ -83,15 +125,17 @@ export function settle(rounds = 2): Promise<void>
 }
 
 /**
- * Renders `view()` with the server renderer, hydrates a second `view()` over
- * that markup, and returns every disagreement. An empty array means the
- * component hydrates cleanly; the container is discarded afterwards.
+ * Renders `view` with the server renderer, hydrates it over that markup,
+ * and returns every disagreement. Each pass calls `view` inside its own
+ * owner, so the effects and `onDispose` cleanups a component registers end
+ * before the helper returns. An empty array means the component hydrates
+ * cleanly; the container is discarded afterwards.
  */
-export function hydrationMismatches(view: () => unknown): HydrationMismatch[]
+export function hydrationMismatches(view: () => Renderable): HydrationMismatch[]
 {
     const container = document.createElement("div");
-    container.innerHTML = renderToString(view());
-    const result = hydrate(view(), container);
+    container.innerHTML = renderToString(view);
+    const result = hydrate(view, container);
     const mismatches = [...result.mismatches];
     result.dispose();
     return mismatches;
@@ -103,22 +147,43 @@ export type AccessibilityCode = "image_without_alt" | "control_without_label" |
 /** One defect found by `accessibilityIssues`. */
 export interface AccessibilityIssue
 {
+    /** Which check the element failed, such as `image_without_alt`. */
     readonly code: AccessibilityCode;
+    /** The element that failed the check, found inside the container passed to `accessibilityIssues`. */
     readonly element: Element;
 }
 
-function hasName(element: Element): boolean
+/** True when an element has an accessible name from an attribute: `aria-label`, `aria-labelledby`, or `title`. */
+function namedByAttribute(element: Element): boolean
 {
-    const label = element.getAttribute("aria-label") ?? "";
-    if (label.trim() !== "" || element.hasAttribute("aria-labelledby") || (element.getAttribute("title") ?? "").trim() !== "")
+    return (element.getAttribute("aria-label") ?? "").trim() !== "" || element.hasAttribute("aria-labelledby") || (element.getAttribute("title") ?? "").trim() !== "";
+}
+
+/** The text an element shows to assistive technology: its text content, leaving out every `aria-hidden="true"` subtree. */
+function exposedText(element: Element): string
+{
+    let text = "";
+    for (const node of element.childNodes)
     {
-        return true;
+        if (node.nodeType === Node.TEXT_NODE)
+        {
+            text += node.textContent ?? "";
+        }
+        else if (node instanceof Element && node.getAttribute("aria-hidden") !== "true")
+        {
+            text += exposedText(node);
+        }
     }
-    if ((element.textContent ?? "").trim() !== "")
+    return text;
+}
+
+function hasName(element: Element): boolean
+{
+    if (namedByAttribute(element) || exposedText(element).trim() !== "")
     {
         return true;
     }
-    return [...element.querySelectorAll("img[alt]")].some((image) => (image.getAttribute("alt") ?? "").trim() !== "");
+    return [...element.querySelectorAll("img[alt]")].some((image) => (image.getAttribute("alt") ?? "").trim() !== "" && image.closest("[aria-hidden=\"true\"]") === null);
 }
 
 function isLabeled(control: Element): boolean
@@ -128,7 +193,8 @@ function isLabeled(control: Element): boolean
         return true;
     }
     const id = control.getAttribute("id");
-    return id !== null && id !== "" && control.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`) !== null;
+    const tree = control.getRootNode() as ParentNode;
+    return id !== null && id !== "" && [...tree.querySelectorAll("label[for]")].some((label) => (label as HTMLLabelElement).htmlFor === id);
 }
 
 /**
@@ -168,7 +234,7 @@ export function accessibilityIssues(container: ParentNode): AccessibilityIssue[]
     }
     for (const frame of container.querySelectorAll("iframe"))
     {
-        if ((frame.getAttribute("title") ?? "").trim() === "")
+        if (!namedByAttribute(frame))
         {
             issues.push({ code: "frame_without_title", element: frame });
         }