admin/action-topology-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: verify locators with context evidence

Browse Source
This commit is contained in:
赵义仑
2026-06-16 20:02:25 +08:00
parent 581724ea42
commit c41f260e51
5 changed files with 281 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
src/locator.ts
View File

@@ -1,9 +1,9 @@
import type { Locator, Page } from "playwright";
import { shortHash } from "./hash.js";
import type { LocatorCandidate, LocatorDescriptor, RawActionableElement } from "./types.js";
import type { LocatorCandidate, LocatorDescriptor, LocatorScopeDescriptor, RawActionableElement } from "./types.js";
export function generateLocators(elementId: string, raw: RawActionableElement): LocatorCandidate[] {
const candidates: Array<Omit<LocatorCandidate, "locatorId" | "elementId" | "verified" | "failureCount">> = [];
const candidates: Array<Omit<LocatorCandidate, "locatorId" | "elementId" | "verified" | "failureCount" | "identity">> = [];
const name = clean(raw.accessibleName);
const label = clean(raw.label);
const placeholder = clean(raw.placeholder);
@@ -11,6 +11,14 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
const testId = raw.attributes["data-testid"] || raw.attributes["data-test-id"] || raw.attributes["data-test"];
const id = raw.attributes.id;
const nameAttr = raw.attributes.name;
const scopes = contextScopes(raw);
const evidence = [
{
level: "derived" as const,
source: "locator.generator",
description: "Locator candidate generated from state-local element semantics",
},
];
if (raw.role && name) {
candidates.push({
@@ -20,6 +28,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.getByRole(${JSON.stringify(raw.role)}, { name: ${JSON.stringify(name)} })`,
score: 0.95,
reason: "role plus accessible name",
scopes,
evidence,
});
}
@@ -31,6 +41,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.getByTestId(${JSON.stringify(testId)})`,
score: 0.92,
reason: "explicit test id",
scopes,
evidence,
});
}
@@ -42,6 +54,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.getByLabel(${JSON.stringify(label)})`,
score: 0.9,
reason: "associated label",
scopes,
evidence,
});
}
@@ -53,6 +67,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.getByPlaceholder(${JSON.stringify(placeholder)})`,
score: 0.86,
reason: "placeholder text",
scopes,
evidence,
});
}
@@ -64,6 +80,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.getByText(${JSON.stringify(text)}, { exact: true })`,
score: 0.75,
reason: "visible text fallback",
scopes,
evidence,
});
}
@@ -75,6 +93,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.locator(${JSON.stringify(`#${cssEscape(id)}`)})`,
score: 0.72,
reason: "id selector fallback",
scopes,
evidence,
});
}
@@ -86,6 +106,8 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
expression: `page.locator(${JSON.stringify(`${raw.tag}[name="${cssString(nameAttr)}"]`)})`,
score: 0.68,
reason: "name attribute fallback",
scopes,
evidence,
});
}
@@ -94,23 +116,126 @@ export function generateLocators(elementId: string, raw: RawActionableElement):
locatorId: `loc_${shortHash([elementId, candidate.descriptor])}`,
elementId,
verified: false,
identity: null,
failureCount: 0,
}));
}
export async function verifyLocators(page: Page, locators: LocatorCandidate[]): Promise<LocatorCandidate[]> {
export async function verifyLocators(page: Page, raw: RawActionableElement, locators: LocatorCandidate[]): Promise<LocatorCandidate[]> {
const verifiedAt = new Date().toISOString();
const verified: LocatorCandidate[] = [];
for (const locator of locators) {
try {
const matchCount = await resolveLocator(page, locator.descriptor).count();
const resolved = resolveLocator(page, locator.descriptor);
const matchCount = await resolved.count();
const identity =
matchCount === 1
? await resolved.first().evaluate(
(element, expected) => {
const html = element as HTMLElement;
const tag = html.tagName.toLowerCase();
const text = normalizeNullable(html.innerText || html.textContent || "");
const label = getLabel(html);
const placeholder = "placeholder" in html ? normalizeNullable(String((html as HTMLInputElement).placeholder || "")) : null;
const accessibleName = normalizeNullable(getAccessibleName(html) || label || placeholder || text || "");
const inferredRole = html.getAttribute("role") || inferRole(html);
const visible = isVisible(html);
return {
sameTag: tag === expected.tag,
sameRole: expected.role ? inferredRole === expected.role : true,
sameAccessibleName: expected.accessibleName ? accessibleName === expected.accessibleName : true,
sameText: expected.text ? text === expected.text : true,
sameVisibility: visible === expected.visible,
};
function inferRole(item: HTMLElement): string | null {
const itemTag = item.tagName.toLowerCase();
if (itemTag === "button") return "button";
if (itemTag === "a" && item.hasAttribute("href")) return "link";
if (itemTag === "select") return "combobox";
if (itemTag === "textarea") return "textbox";
if (itemTag === "input") {
const type = ((item as HTMLInputElement).type || "text").toLowerCase();
if (["button", "submit", "reset"].includes(type)) return "button";
if (type === "checkbox") return "checkbox";
if (type === "radio") return "radio";
return "textbox";
}
return null;
}
function getAccessibleName(item: HTMLElement): string | null {
const ariaLabel = item.getAttribute("aria-label");
if (ariaLabel) return normalizeNullable(ariaLabel);
const labelledBy = item.getAttribute("aria-labelledby");
if (labelledBy) {
const labelledText = labelledBy
.split(/\s+/)
.map((id) => document.getElementById(id)?.innerText || document.getElementById(id)?.textContent || "")
.join(" ");
if (labelledText.trim()) return normalizeNullable(labelledText);
}
const title = item.getAttribute("title");
if (title) return normalizeNullable(title);
const alt = item.getAttribute("alt");
if (alt) return normalizeNullable(alt);
return normalizeNullable(item.innerText || item.textContent || "");
}
function getLabel(item: HTMLElement): string | null {
const id = item.getAttribute("id");
if (id) {
const explicit = document.querySelector<HTMLLabelElement>(`label[for="${CSS.escape(id)}"]`);
if (explicit) return normalizeNullable(explicit.innerText || explicit.textContent || "");
}
const implicit = item.closest("label");
if (implicit) return normalizeNullable(implicit.innerText || implicit.textContent || "");
return null;
}
function isVisible(item: HTMLElement): boolean {
const style = getComputedStyle(item);
if (style.visibility === "hidden" || style.display === "none" || Number(style.opacity) === 0) return false;
const rect = item.getBoundingClientRect();
return rect.width > 0 && rect.height > 0;
}
function normalizeText(value: string): string {
return value.replace(/\s+/g, " ").trim();
}
function normalizeNullable(value: string): string | null {
const normalized = normalizeText(value);
return normalized || null;
}
},
{
tag: raw.tag,
role: raw.role,
accessibleName: raw.accessibleName,
text: raw.text,
visible: raw.visibility.visible,
},
)
: null;
const identityMatches = identity ? Object.values(identity).every(Boolean) : false;
const locatorVerified = matchCount === 1 && identityMatches;
verified.push({
...locator,
verified: matchCount === 1,
verified: locatorVerified,
matchCount,
lastVerifiedAt: verifiedAt,
score: matchCount === 1 ? locator.score : Math.max(0.1, locator.score - 0.35),
score: locatorVerified ? locator.score : Math.max(0.1, locator.score - (matchCount === 1 ? 0.2 : 0.35)),
identity,
evidence: [
...locator.evidence,
{
level: locatorVerified ? "verified" : "observed",
source: "locator.verify",
description: `Locator matched ${matchCount} element(s)`,
},
],
});
} catch {
verified.push({
@@ -119,6 +244,11 @@ export async function verifyLocators(page: Page, locators: LocatorCandidate[]):
matchCount: 0,
lastVerifiedAt: verifiedAt,
score: Math.max(0.1, locator.score - 0.45),
identity: null,
evidence: [
...locator.evidence,
{ level: "observed", source: "locator.verify", description: "Locator verification failed before matching elements" },
],
failureCount: locator.failureCount + 1,
});
}
@@ -155,6 +285,13 @@ function dedupeCandidates<T extends { expression: string }>(candidates: T[]): T[
return deduped;
}
function contextScopes(raw: RawActionableElement): LocatorScopeDescriptor[] {
const contexts = [raw.context.dialog, raw.context.row, raw.context.form, raw.context.section, raw.context.landmark, raw.context.listitem];
return contexts
.filter((context): context is LocatorScopeDescriptor => Boolean(context && (context.name || context.text)))
.map((context) => ({ kind: context.kind, name: clean(context.name) ?? null, text: clean(context.text) ?? null }));
}
function clean(value: string | null | undefined): string | undefined {
const cleaned = value?.replace(/\s+/g, " ").trim();
return cleaned || undefined;
@@ -167,4 +304,3 @@ function cssEscape(value: string): string {
function cssString(value: string): string {
return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
}

2
src/snapshot.ts
View File

@@ -68,7 +68,7 @@ export async function snapshotPage(page: Page, openedByEdgeId: string | null = n
rawElement.context.listitem?.name ?? null,
null,
])}`;
const locators = await verifyLocators(page, generateLocators(elementId, rawElement));
const locators = await verifyLocators(page, rawElement, generateLocators(elementId, rawElement));
elements.push({
elementId,
stateId: state.stateId,

17
src/types.ts
View File

@@ -57,6 +57,20 @@ export type LocatorDescriptor =
export type LocatorFramework = "playwright" | "css";
export interface LocatorScopeDescriptor {
kind: ContextAnchor["kind"];
name: string | null;
text: string | null;
}
export interface LocatorIdentityEvidence {
sameTag: boolean;
sameRole: boolean;
sameAccessibleName: boolean;
sameText: boolean;
sameVisibility: boolean;
}
export interface LocatorCandidate {
locatorId: string;
elementId: string;
@@ -69,6 +83,9 @@ export interface LocatorCandidate {
verified: boolean;
lastVerifiedAt?: string;
matchCount?: number;
scopes: LocatorScopeDescriptor[];
identity: LocatorIdentityEvidence | null;
evidence: EvidenceRecord[];
failureCount: number;
}