mcp server

frap

Deterministic UI engine for tests and agents — stable locators and self-healing without ML in core; optional LLM enhancements and MCP tools when you need them.

kotler-dev/frapcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 22, 2026

Frap

Deterministic library for working with locators in test automation. Stable locators when the interface changes.

Frap helps tests survive UI changes: finds elements on a page, remembers their structural fingerprint, and picks a new selector when needed — with a report and a confidence score (0.0–1.0: how sure Frap is that the found element is the same one).

Full locator path: page map → element fingerprint → selector recovery → failure cause analysis → interface change tracking across runs (v1.2.0 — feedback loop, F009; v2.0+ — structural drift and CI gate, F017).

What is Frap

What Frap does:

Find — builds a map of interactive elements with recommended selectors in a single pass, without manual DOM inspection
Hold — when markup changes, restores the link between selector and element by structure, instead of failing on the first diff
Explain — shows confidence, alternative candidates, and why a test failed — not a black-box "fix"

Frap parses element trees (DOM — today; accessibility tree — v1.4+ via CDP, v2.0+ multi-platform, F006), groups similar blocks with deterministic algorithms, and generates stable locators for tests.

Problem

The interface changes faster than tests are updated.

Pain points:

Hours of manual DOM inspection on new pages
Frontend refactoring causes massive selector failures in CI
Unclear why auto-recovery chose a new element
Opaque cloud tools often fail enterprise security requirements

What automators expect:

Take a snapshot of a page and get all available locators
Group elements by structure and business zones
Quickly start PageObject without manual routine
Reduce flaky failures via deterministic logic

Positioning

Frap is a structural and stable identifier layer, not a replacement for your test tools.

Principle: Integration, not replacement.

Playwright (today) / Selenium·WebDriver (v1.4+) / JUnit
        ↓
TypeScript SDK / Java SDK / JSON-RPC
        ↓
Rust Core: fingerprints · clustering · recovery · context

Frap wraps your existing locators and adds structural resilience.

Locator Lifecycle

One clear lifecycle for every locator:

Page map — collect element list: tags, attributes, path, role, text
Element fingerprint — capture stable traits and structural prefix (signature)
Selector recovery — if the element is not found, find the best candidate by confidence and selection rules
Report — what changed, which selector was picked, confidence score, top candidates

Core Features

Page Map (Element Map)

In a single pass, Frap builds a page map — a flat catalog of elements with a recommended selector and confidence score. Not a DOM tree, not querySelector('*'). This catalog is the foundation for PageObjects and baselines.

API: Frap.discover, buildElementMap. Java guide: docs/en/discover-page-object.md.

Clustering

Elements are grouped by structural template:

SINGLE — unique element (button, field)
LIST — two or more similar items (repeating cards, rows)

Five identical cards → one items(index) method, not five copies. Clustering removes noise and narrows the search during selector recovery.

Locator Recovery

When a selector stops finding an element (changed data-testid, class, wrapper), Frap recovers the locator — picks a new selector for the same element:

Compare saved fingerprint against the current page
Rank candidates by confidence score
Decide: recover if confidence ≥ threshold, or fail safely with a report (e.g. two similar candidates — refuse, to avoid clicking the wrong element)

Behavior is deterministic: same input → same output.

API: withFrap, heal, HealResult.

Unified Run Context & Failure Cause Analysis

Unified run context — a single timeline from three sources: UI actions (clicks, locator failures), network (HTTP, timeouts), logs (console, page errors).

Failure cause analysis — after a test fails, Frap inspects this context and answers: UI issue, network issue, timing issue, or unclear. This is not picking a new selector. Example: API timeout → don't "fix" the selector, report a network cause.

API: captureAll, ContextTimeline; analyzeRca → returns RcaReport.

Page Object Generation

Workflow from zero to first tests:

Page map → filter interactive elements → group by clusters → read recommended selectors → generate Page Object skeleton → evolve with baseline fingerprints; UI change tracking across runs — v1.2.0 (F009 feedback), v2.0+ (F017 drift-report)

Java: Discover & Page Object (locator rules, LIST items(index), confidence).

Principles

Explainable by design — every decision shows its work
No ML by default — deterministic algorithms, same input → same output
On-prem first — works without cloud APIs
Integration, not replacement — complements Playwright, Selenium, and JUnit

Architecture

Unified Rust Core

Single source of truth for fingerprints, clustering, and locator recovery
Consistent behavior across Java, TypeScript, and future SDKs
Performance and determinism without divergence

Thin SDK Adapters

JSON-RPC contract and DTO schema for all transports
Contract tests for every SDK
API convenience without duplicating logic

You own your fingerprints and can reproduce behavior across stacks.

API Summary

Names in the table are the target Core/RPC contract; concrete SDKs may differ (e.g. HealingEngine.heal() in TypeScript).

Action	API	Purpose
Page map	`Frap.discover`, `buildElementMap`	Snapshot → element catalog
Filter	`filterElementMap`, `FilterSpec`	Interactive only, min cluster size
PO generation	`generatePageObject`, `GenerateOptions`	Page Object skeleton
Locator recovery	`withFrap`, `heal` → `HealResult`	Pick a new selector
Unified run context	`captureAll`, `ContextTimeline`	UI + network + logs
Failure cause analysis	`analyzeRca` → `RcaReport`	Classify: UI / network / timing

Packages

Registry	SDK / Core	Playwright	MCP (agents)
npm	`@frap/sdk`	`@frap/playwright`	—
Maven	`io.github.kotler-dev:frap-core-java`	`io.github.kotler-dev:frap-playwright`	`frap-mcp-stdio`, `frap-mcp-http`, `frap-mcp-http-local`

Maven 1.1.0 on Maven Central (io.github.kotler-dev, tag java-v1.1.0):

Artifact	Version	JDK
`frap-core-java`	1.1.0	17
`frap-playwright`	1.1.0	17
`frap-mcp-tools`, `frap-mcp-stdio`, `frap-mcp-http`, `frap-mcp-http-local`	1.1.0	21 (sidecar)

<dependency>
  <groupId>io.github.kotler-dev</groupId>
  <artifactId>frap-core-java</artifactId>
  <version>1.1.0</version>
</dependency>

Guides: Java SDK · frap-mcp · Discover & PO

Development: 1.1.1-SNAPSHOT on branch develop/java-v1.1.1 — PRs for Java/MCP go there.

Note: npm requires scoped install @frap/...; Maven uses io.github.kotler-dev groupId.

Release notes (Java SDK)

1.1.0 — 2026-06-03 (`java-v1.1.0`)

Semantic locator pipeline in Rust Core: CLASSIFY→SCOPE→LOCATE→VERIFY→HEAL
Page Object generation: Playwright getByTestId, getByRole, getByText, scoped locators
dom-benchmark (9 pages) + F019 discover quality
MCP on Maven Central: 6 tools, stdio / http / http-local runners (JDK 21 sidecar; library stack JDK 17)
Six-platform bundled frap-core-rpc in frap-core-java

Full changelog: CHANGELOG.md

Previous Java lines

1.0.1 — F019 discover prep, MCP initial Central line (superseded by 1.1.0)
1.0.0 — first Maven Central release (frap-core-java, frap-playwright)

Documentation

Topic	Link
Changelog	CHANGELOG.md
Java development branch	sdk/java/DEVELOPMENT.md
Discover & Page Object (Java)	docs/en/discover-page-object.md
Examples (by language)	examples/
FixtureConf demo app	fixtures/fixtureconf/
Java SDK	sdk/java/README.md
Java MCP	sdk/java/frap-mcp/README.md
TypeScript SDK	sdk/typescript/README.md
Java example (Playwright)	examples/java/playwright/
TypeScript example (Playwright)	examples/typescript/playwright/
Playwright adapter (TS)	adapters/playwright/README.md
Playwright adapter (Java)	adapters/playwright-java/README.md
Rust core	crates/core/README.md

Roadmap

1.0.0 — core + Java SDK: page map, locator recovery, reports, context and RCA, PO generation (Maven Central)
1.0.1 — Java: F019 discover/PoG quality, dom-benchmark, six-platform RPC, MCP (java-v1.0.1, superseded by 1.1.0)
1.1.0 — Java: semantic locator pipeline, PoG getBy* APIs, MCP on Maven Central (java-v1.1.0) ← current release
1.1.1 — in development on develop/java-v1.1.1 (SNAPSHOT)
1.2.0 — feedback loop (F009), npm parity for discover/PO
1.4+ — CDP source (incl. web accessibility tree), WebDriver/Selenide (F014)
2.0+ — structural contracts and drift gate (F017), visual fingerprints (F007), health score (F010), multi-platform and accessibility tree (F006)

Let's frap

Examples · Java SDK · TypeScript SDK

License

Apache-2.0 — see LICENSE and NOTICE.