---
title: Web-App Verification (Obscura)
---

# Web-App Verification (Obscura)

## What it is

> Status: **shipped** — available to all users. The verify tool activates once you install Obscura (Settings → "Set it up for me").

When you have an Omniscio coding session build you a **web app**, this feature lets the
agent **functionally verify that the app actually works** before it says "done" —
the way a careful developer would click through their own work. It does this with
**Obscura**, a lightweight Rust headless browser, instead of installing full
Chrome/Chromium.

The agent gets a single tool, **`verify_web_app`**, that opens the running app in
Obscura and checks things like: does the page load, is the login button present,
does clicking it go to the right place, do forms accept input, are there any
JavaScript errors in the console.

## Where to find it

Obscura is opt-in and installed on demand through the toolchain "Set it up for me" flow, and the capability itself is enabled at **Settings → Lab** (Web-app verification). After that there is no button per run: the agent gets the tool on a web-app project and uses it by itself.

## How it behaves

### What it is NOT

Obscura has **no rendering/layout engine** (it runs JavaScript and builds the page
in memory, but never draws pixels). So this is a **functional** test tool, not a
visual one:

- ✅ It checks: page loads, elements exist, text is present, navigation works,
  forms accept input, no console errors.
- ❌ It cannot: take screenshots, do visual/pixel comparison, or judge how the
  page _looks_. Asking it for a screenshot returns a clear "functional-only"
  message rather than silently passing.

"Like Playwright" is achieved by literally **using Playwright** (`playwright-core`)
and pointing it at Obscura over the Chrome DevTools Protocol — so the checks run
through the real Playwright engine, just against a lighter browser.

### How it works (under the hood)

1. Omniscio detects the project is a web app (Next.js, Vite, SvelteKit, Nuxt, Astro,
   Remix, Gatsby, Angular).
2. If Obscura is installed **and** you've enabled the capability, Omniscio adds a
   built-in `webapp-verify` tool server to that session — all three conditions
   must hold (`shouldMountWebappVerify`).
3. The agent starts the dev server itself (e.g. `npm run dev`) and learns its URL.
4. The agent calls `verify_web_app({ url, checks })`.
5. Omniscio launches Obscura on a private loopback port, connects `playwright-core`,
   runs each check, and returns a structured pass/fail report (plus any console
   errors). A green run posts a visible "✓ Verified working" row.

### The checks

| Check             | Asserts                                               |
| ----------------- | ----------------------------------------------------- |
| `loads`           | the app reaches the URL without crashing              |
| `selectorPresent` | an element matching a CSS selector exists             |
| `textContains`    | the page body contains some text                      |
| `clickNavigates`  | clicking an element leads to an expected element/page |
| `fill`            | a form field accepts a value                          |
| `noConsoleErrors` | no `console.error` or uncaught errors occurred        |

### Setup

Obscura is **opt-in** and installed on demand (it is not bundled with Omniscio):

1. Install it via the toolchain "Set it up for me" flow — Omniscio downloads the pinned
   Obscura release for your OS and verifies its SHA-256 checksum before use.
2. Enable **Web-app verification** in Settings → Lab.

**Proactive nudge:** the first time you build a web app without Obscura installed,
Omniscio drops a single dismissible inbox card offering one-click setup (once per
install, never nags). It only appears once the feature is visible to you, so a
still-in-development build never markets it broadly.

## For agents

### Key code

- `src/main/services/webapp-verify/` — the engine: `check-types.ts` (Zod schema,
  enforces functional-only), `check-runner.ts` (pure check logic), `obscura-process.ts`
  (launch Obscura on an ephemeral port + health wait), `obscura-harness.ts`
  (`connectOverCDP` glue), `gate.ts` (`shouldMountWebappVerify`),
  `is-web-app-project.ts`, `checksum.ts`.
- `src/main/services/webapp-verify-mcp-server/` — the built-in stdio MCP server
  exposing the single `verify_web_app` tool.
- Setting: _(retired 2026-09-19 with the rest of the per-session MCP composition)_ —
  the `webAppVerifyEnabled` toggle and the `webapp-verify` MCP server are gone from
  sessions. The `webapp-verify` feature id stays in `UNRELEASED_FEATURES` marked
  `retired` (hidden for everyone), and the engine + server source stay in the tree,
  unwired.

Design + plan: `docs/superpowers/specs/2026-06-16-obscura-webapp-testing-design.md`,
`docs/superpowers/plans/2026-06-16-obscura-webapp-verify.md`.

## Related

[MCP Servers](mcp-servers.md) covers how a built-in tool server like this one is mounted into a session and managed. [Running Apps](running-apps.md) covers the preview surface for the dev server an agent starts before it verifies the app.