Approxima-OSS is an open-source, agent-based web end-to-end testing platform, licensed under MIT. Its core idea is: tests are written using natural-language intent rather than hard-coded selectors, so tests do not break when the DOM changes. Users describe a test journey in English (for example, "add an item to the cart and verify the total updates"), and an LLM-driven browser agent executes it step by step in a real browser, taking screenshots after each step and visually verifying before continuing to the next step.
Main capabilities
Goal Mode: There is no need to provide specific steps; just provide an English goal (for example, "sign up, create a project, and invite a teammate"), and the agent runs in exploration mode until the goal is completed, then writes the discovered steps back to the journey and immediately triggers a verification run to prove reproducibility. After that, the journey runs with fixed deterministic steps.
Self-healing: When an application change causes the description of a step to no longer match reality, the agent does not fail directly; instead, it infers what the step should be and reports the refined step alongside the run result. These suggestions appear inline in the journey editor and can be accepted or ignored with one click. Suggestions are reviewed by an LLM before being shown, to filter out meaningless rewrites. The agent also attempts to refine steps on each pass, so the next run consumes fewer tokens and less time.
Streaming execution and subtitles: Each run streams the browser's live screen recording to the dashboard, and the agent narrates its reasoning in subtitles ("the cart icon shows 0, looking for an add button"), the actions performed, and the pass or fail of each check. When something goes wrong, you can see what the agent saw and why it made its judgment, without digging through logs.
Skills: Skills are reusable step sequences (for example, "login": enter email, enter password, click submit), and journeys can reference a skill as a single step. Skills are expanded inline at runtime, so updating a skill updates all journeys that use it. Goal Mode runs are also aware of the skill library, and when a discovered step matches an existing skill, it collapses back into a single skill reference instead of duplicating steps.
Agent fine-tuning and shadow runs: Agents are versioned, and each (journey, exploration) agent is located in a version folder under web-runner/src/agent/, and each run records the version used. A beta version can be registered in shared/agent-versions.ts and AUTO_SHADOW_ENABLED can be enabled, whichEach real run generates a paired shadow run on the same journey, and the admin panel compares the two populations with paired statistics.
Variables and secrets: steps can reference variables using the $NAME syntax, values are stored per app and resolved at dispatch time. Variables marked as secrets are encrypted at rest (AES-256-GCM), masked in the dashboard (••••••••), and purged from stored run logs. Step suggestions are generated based on unresolved $NAME tags, so self-healing does not bake secrets into journeys. But for the agent to log into the app, it must enter the actual values, so secrets leave your machine, appear in the prompts the agent receives and the screenshots it reviews, and thus reach the LLM provider you configured. De-secreting only controls where the values ultimately reside (database, dashboard, suggestions) and cannot withdraw them from the model. Therefore, secrets used in Approxima should be limited to unimportant test workspaces.
How the agent drives the browser: the agent works from screenshots but acts on the DOM. Clicks use an element-first, coordinate-disambiguation approach: the agent reads the target from the screenshot (visible text, aria label, or CSS selector) and approximate pixel coordinates, the target is resolved in a layered priority order (role, text, CSS selector), and finally a real Playwright element click is executed. Screenshots capture the viewport by default (1280×720 by default, 390×844 in mobile mode), and a 400×400 region can also be cropped on demand to inspect details.
How to use
Architecture: the API queues runs to Postgres and dispatches them to web-runner; web-runner launches a local Chromium, drives it step by step with the configured LLM, and reports results via callback.
Prerequisites: Node 20+, a Postgres database, an S3-compatible storage bucket for screenshots, and at least one LLM API key (OpenAI, Anthropic, or Gemini).
Steps: create the database tables (apply the migrations in api/drizzle/ via Drizzle), configure the API, configure the web runner, open the http://localhost:3000（无需登录），创建指向待测 URL app, and write your first journey (or just give a goal and let the agent discover the steps on its own).
Log in to the app under test: add steps like a user, for example "enter $TEST_EMAIL in the email field, enter $TEST_PASSWORD, click login", with credentials stored as app variables (Settings → Variables and Secrets).
Iterate on the agent: copy web-runner/src/agent/<type>/v1/ to v2/, add it to the version map in <type>/index.ts, and register it in shared/agent-versions.ts (AVAILABLE_VERSIONS, and BETA_VERSIONS for shadow testing).
Deploy: the API is deployed together with the dashboard as a single Cloudflare Worker; the web runner can be deployed on any Node host capable of running Chromium, pointed to via WEB_RUNNER_URL / WEB_RUNNER_API_KEY. Database migrations use Drizzle commands.
Applicable scenarios and limitations
Applicable scenarios: end-to-end testing of web apps that need rapid iteration and frequent releases; teams that want to maintain tests in natural language and avoid the burden of selector maintenance; organizations that want to self-host test data and results and not depend on third-party hosted QA platforms.
Limitations: there is no user authentication, and the dashboard and API are open to anyone who can access them, so they should run on localhost, a private network, or behind your own authentication proxy. Secrets are sent to the LLM provider, so they should be used only in unimportant test workspaces. You need to provide your own Postgres, S3-compatible storage, and LLM API key.
