ATOM

Governed AI testing for web, API and mobile.

ATOM is an Automated Testing and Orchestration Mesh. It turns plain-language requests into UI, API, visual and native mobile tests, then runs them in isolated workers behind policy checks, human approval and a full audit trail.

Replayable runs. Real-user coverage with Atom Pulse. Built for teams that need speed without losing control.

$npm ci && npm run dev

Safe development profile. Execution stays disabled until you configure a hardened worker.

  • 4-stagegoverned lifecycle
  • UI · API · Mobileone orchestration mesh
  • Human-approvedevery AI-generated test
  • Audit-readyreplayable evidence
Explore ATOM

Pick a feature and see it in action

Everything ATOM does for governed, AI-assisted testing, one card at a time. Open any card, and come back whenever you like.

Start here

Product Overview

What ATOM is, and the live governed-run lifecycle at a glance.

OverviewLive demo
1 minExplore
Interactive

Governed Run Walkthrough

Step through a request to a replayable run: plan, approve, execute and keep the evidence.

4 stagesApprovalAudit trail
Step by stepExplore
Core

Test Surfaces

UI, API, visual, mixed and mobile coverage through one governed workflow.

UIAPIVisualMobile
One meshExplore
iOS & Android

Mobile Automation

Generate and run native mobile tests through a managed execution boundary.

AppiumiOSAndroid
Managed workersExplore
New feature

Atom Pulse

Find the real-user journeys nobody tested, and ask the “Hey Atom” voice copilot to close the gap.

Real-user coverageVoicePrivacy-first
Coverage gapsExplore
API

API Test Chaining

Chain API tests with controlled data flow instead of ad-hoc scripts.

Data flowAssertionsReusable
WorkflowsExplore
Try it

Live API Simulator

Watch a governed API chain move through the mesh, and export the results.

Hands-onJSONPDF export
InteractiveExplore
Trust

Governance & Controls

Automation that is fast and accountable: policy, RBAC and human approval.

RBACPolicyTenant isolation
Built inExplore
Platform

Architecture

A control plane kept separate from isolated execution workers.

Control planeWorkersIsolation
Under the hoodExplore
Assurance

Security & Compliance

Operational controls delivered as product features, ready for audit.

SOC 2Audit logsSecrets
Audit-readyExplore
Go

Get Started

Bring controlled testing into your delivery workflow in a few steps.

SetupQuick start
Few minutesExplore
Enterprise testing control plane Tenant-isolated & approval-gated

Test with AI.
Operate with confidence.

ATOM connects AI-assisted test generation to a governed execution mesh. Teams can design UI, API, visual, mixed, and native mobile tests while keeping policy, approvals, tenant boundaries, and evidence in the path of execution.

UI · API · Visual · Mobile
Tenant-aware · Approval-gated
Web, Visual & API Mesh
Isolated Playwright Worker 1.62.1

Governed AI Generation & Isolated Execution

  • ✓Generates and normalizes Playwright specifications (chromium, firefox, webkit) through an allowlisted AI gateway with redaction, budgets, and audit events.
  • ✓Declarative api-test-plan/v1 chaining with safe response extraction ({{chain.variable}}), endpoint allowlists, and managed egress gates.
  • ✓Execution is disabled by default (EXECUTION_ENABLED=false) and runs only when a digest-pinned, non-root Playwright worker image is configured.
  • ✓Includes vendored Aegis QA SDK (tools/aegis-qa) for local, confidence-gated click/fill locator self-healing.
  • ✓Treats generated code as untrusted input — denies child_process, eval, process.env, and filesystem access before submission.
Native Mobile Automation
Immutable Appium Worker

Managed iOS (XCUITest) & Android (UiAutomator2)

  • ✓Generates WebdriverIO TypeScript tests using @wdio/globals and stable accessibility-id locators such as ~primary-action.
  • ✓Fail-closed admission: requires APPIUM_EXECUTION_ENABLED=true, SHA-256 digest-pinned APPIUM_WORKER_IMAGE, and APPIUM_NETWORK_NAME.
  • ✓Connects only to credential-free HTTPS platform device brokers (APPIUM_IOS_DEVICE_BROKER_URL / APPIUM_ANDROID_DEVICE_BROKER_URL).
  • ✓Worker runs non-root with read-only filesystem, cap-drop=ALL, no-new-privileges, CPU/memory/PID limits, and no USB mounts.
  • ✓Generated scripts cannot create remote sessions or read environment variables; writes JUnit evidence to /results/results.xml.
ATOM Governed Execution Mesh — Principle 01: Untrusted Input · Principle 02: Isolated & Policy Mediated · Principle 03: Tenant-Scoped Evidence
Click any stage to inspect it in the interactive walkthrough below
Natural-Language Intent
UI · API · Visual · Mixed · Mobile
Tenant Evidence
Signed S3 URLs · Audit · Retention
Stage 1 · Generate — Natural-language requests are normalized into validated test specifications via the allowlisted AI gateway.
🛡️ State machine: requested → validated → queued → assigned → running → collecting_artifacts → passed|failed
Live, durable operations

From a request to a replayable run.

Step through ATOM's 4-stage governed lifecycle — Generate, Govern, Execute, and Observe — or press play to see how requests move through the Express API, policy gates, isolated workers, and AtomRunStream.

⚛ ATOM Control Plane Tenant: acme-dev · Project: website-smoke Governed Lifecycle

Press play to step through Generate, Govern, Execute, and Observe.

One orchestration mesh

Coverage that extends beyond the browser.

ATOM provides a common, governed workflow across the test surfaces that modern delivery teams need to validate.

AI test generation

Turn intent into structured test specifications.

Natural-language requests are normalized through an allowlisted AI gateway with budgeting, redaction, evaluation, and auditable events.

UI and visual testing

Validate behavior and experience.

Build Playwright-based workflows for browser interaction, responsive checks, screenshots, traces, and failure-focused evidence.

API test plans

Chain APIs without unsafe scripting.

Declarative plans support safe response extraction and parameter forwarding while preserving endpoint allowlists and egress controls.

Mixed test definitions

Coordinate application journeys.

Combine API assertions and browser verification into one governed run model rather than stitching disconnected tools together.

Native mobile automation

Generate and run managed iOS and Android workflows.

Create platform-specific WebdriverIO TypeScript for XCUITest and UiAutomator2, then execute through ATOM’s configured immutable Appium worker.

Vendored Aegis QA

Confidence-gated self-healing locators.

Tries the original locator first, heals only failed click/fill actions, rejects ambiguous candidates, and writes accepted repairs to aegis-healing.patch.json.

Native mobile automation

Generate and run iOS and Android automation through a managed execution boundary.

ATOM supports a mobile generation type that requires a declared platform. It emits managed WebdriverIO TypeScript with stable accessibility-id locators; native execution uses a separate immutable Appium worker and the approved platform device broker.

iOS XCUITest HTTPS iOS device broker on the Appium-private network · Uses @wdio/globals and accessibility-id locators such as ~primary-action.
Android UiAutomator2 HTTPS Android device broker on the Appium-private network · Uses @wdio/globals and accessibility-id locators such as ~primary-action.
Variable Required Purpose
APPIUM_EXECUTION_ENABLEDYesMust be true to enable native execution admission.
APPIUM_WORKER_IMAGEYesImmutable Appium worker image (@sha256:<64-hex-digest> in prod).
APPIUM_NETWORK_NAMEYesPrivate Docker network joining worker to approved device brokers only.
APPIUM_ANDROID_DEVICE_BROKER_URLAndroidCredential-free HTTPS endpoint for the managed Android broker.
APPIUM_IOS_DEVICE_BROKER_URLiOSCredential-free HTTPS endpoint for the managed iOS broker.
APPIUM_MAX_CONCURRENT_TESTSNoBounded Appium-worker concurrency; defaults to 1.
mobile / managed execution POST /api/generate/test · Appium
curl -sS -X POST "${ATOM_API}/api/generate/test" \
  "${ATOM_HEADERS[@]}" \
  --data '{
    "prompt": "Validate checkout completion and show the confirmation state.",
    "testType": "mobile",
    "options": {
      "mobile": {
        "platform": "ios",
        "deviceName": "iPhone 16"
      },
      "timeout": 90000
    }
  }' | jq

# Build the immutable Appium worker image
docker build \
  --file workers/appium/Dockerfile \
  --tag atom-appium-worker:local \
  .
✓

Fail closed by design. Native execution is available only when a SHA-256-pinned Appium worker, private worker network, and credential-free HTTPS device broker are configured for the selected platform. The worker runs non-root with a read-only filesystem, cap-drop=ALL, no-new-privileges, and writes JUnit evidence to /results/results.xml.

New · Atom Pulse

Test what your customers actually do, not just what you remembered to test.

Atom Pulse turns anonymized real-user journeys into a ranked list of untested paths. It reports a real-user coverage percentage, then drafts a regression test for each gap through the same governed pipeline: policy checks, human approval, and audit trail.

1 · Capture Privacy-first SDK One script tag records navigation, clicks, submits, JS errors and failed requests. It never records typed values and honors Do Not Track.
2 · Mine Journeys, ranked by risk Sessions are scrubbed, grouped into journeys, and scored by traffic, error rate and revenue paths such as checkout.
3 · Close the gap Governed test generation One click sends a gap to the AI gateway. The drafted test still goes through approval before anything runs.
4 · Ask “Hey Atom” voice copilot Ask “How well are my customers covered?”, “Which journeys are most at risk?” or “Write a test for my riskiest journey”. Uses the browser’s built-in speech, with no extra service.
Endpoint Credential Purpose
POST /api/pulse/ingestIngest-only keyBrowser SDK sends events. Write-only; grants no read access.
GET /api/pulse/gapspulse:readRanked untested journeys with suggested test prompts.
GET /api/pulse/summarypulse:readPlain-language coverage summary used by the voice copilot.
POST /api/pulse/keyspulse:manageCreate, list or revoke ingest keys (admins only, audited).
pulse / real-user coverage SDK · /api/pulse
<!-- 1. Add to your site -->
<script src="https://YOUR-ATOM/atom-pulse.js"
        data-endpoint="https://YOUR-ATOM-API/api/pulse/ingest"
        data-key="apk_..." async></script>

# 2. See what is untested
curl -sS "${ATOM_API}/api/pulse/gaps" \
  "${ATOM_HEADERS[@]}" | jq '.realUserCoveragePercent, .gaps[0]'

# 3. Ask Atom out loud (Pulse page)
"Hey Atom, write a test for my riskiest journey."
✓

Privacy and governance by design. Emails, tokens and long numbers are redacted on ingest; URLs are templated (/orders/:id); keys are stored hashed, bound to one tenant, and revocable. Journeys are tenant-isolated, and generated tests keep Atom’s approval gates.

API testing and orchestration

Chain API tests with controlled data flow, not ad-hoc scripts.

ATOM accepts a versioned api-test-plan/v1 contract. Each plan is declarative: it defines bounded requests, assertions, safe response extraction, and later placeholder resolution without allowing arbitrary code execution.

api-test-plan/v1 Declarative Forward-Only Chaining Example
{
  "environment": "staging",
  "steps": [
    {
      "id": "create-order",
      "request": { "method": "POST", "path": "/v1/orders" },
      "assertions": [{ "type": "status", "equals": 201 }],
      "extract": [{ "name": "orderId", "path": "$.id", "classification": "internal" }]
    },
    {
      "id": "get-order",
      "request": { "method": "GET", "path": "/v1/orders/{{chain.orderId}}" },
      "assertions": [{ "type": "json_path_equals", "path": "$.state", "equals": "created" }]
    }
  ]
}
⊕

Forward-only chaining. A step can capture a named value from a response and reference it in a later request with {{chain.variable}}. Duplicate variables, unresolved placeholders, unsafe JSON paths, and forward references are rejected before execution.

Contract

Constrain the request surface.

Plans require a name, environment, bounded unique steps, allowlisted HTTP methods, relative paths, JSON-only bodies, and normalized headers. The test specification validates the API plan before it becomes executable.

Assertions

Make response expectations explicit.

Use status checks, JSON-path existence or equality checks, and header equality checks. A failed assertion ends the dependent chain so later requests cannot run against an invalid state.

Extraction

Pass values safely between steps.

Extraction rules accept safe body JSON paths and record only presence and classification in step results. Secret-classified values are not surfaced in live or result payloads.

Orchestration

Keep run state durable and observable.

Authorized submission, idempotency, policy gates, isolated execution, and replayable lifecycle events preserve an accountable path from request through evidence.

Interactive sandbox

See a governed API chain move through the mesh.

This browser-only simulation follows a synthetic order workflow. It does not send requests to a live service, retain data, or expose secret values.

Simulated authentication

Only this label is used. Credential values are never requested, retained, logged, or exported.

Ready to simulate

ATOM Run Console
OAuth2 simulation
  1. 1Validate
  2. 2Govern
  3. 3Execute
  4. 4Reconcile
01Create orderPOST /v1/orders
Awaiting execution
02Retrieve orderGET /v1/orders/{{chain.orderId}}
Awaiting execution
03Verify receiptGET /v1/orders/{{chain.orderId}}/receipt
Awaiting execution
Governance in the execution path

Automation should be fast, not unaccountable.

ATOM keeps the test lifecycle explicit from request to retained evidence. It supports a least-privilege identity model and fails closed when the prerequisites for safe execution are absent.

01

Identity and tenant context

OIDC-ready authentication, role-based permissions (viewer, developer, approver, admin, owner), and tenant-scoped access to runs, approvals, audit events, and artifacts.

ENFORCED
02

Policy and approvals

Execution decisions bind the specification, intent, idempotency key, session, and policy version to prevent replay or substitution.

BOUND
03

Isolated execution

Runs dispatch to a hardened Playwright or Appium worker image with constrained results, artifact quotas, and a fail-closed egress posture.

ISOLATED
04

Evidence and retention

Authorization-aware artifact access, durable run states, replayable events (AtomRunStream), audit records, and configurable retention tombstones.

TRACEABLE
Architecture and durable operations

Control plane separated from isolated execution workers.

PostgreSQL is the source of truth for runs, state transitions, event history, audit records, artifact metadata, and quota usage. Redis/BullMQ coordinates durable job dispatch, and S3-compatible storage holds private tenant-scoped artifacts.

  • Identity + RBAC Boundary Development headers, HS256 JWTs & OIDC/SAML role mapping
  • Allowlisted AI Gateway Input redaction, token budgets, AI evaluation harness & audit events
  • Policy & Approval Engine Single-use approvals, domain denylists & timeout guardrails
  • PostgreSQL & Redis/BullMQ Run state machine, idempotency keys & sequence-numbered events
  • Authorization-Aware S3 Artifacts Private object storage, short-lived signed URLs & retention cleanup
  • Immutable Playwright & Appium Workers Digest-pinned, non-root containers with Trivy CVE gating
Endpoint Permission / Access Purpose
GET /api/health · GET /api/readyzPublic operationalService liveness and production dependency readiness checks.
POST /api/generate/testAuthenticated tenantGenerates and normalizes ui, api, visual, mixed, or mobile test specifications.
POST /api/execute/testdeveloper / approver / admin / ownerIdempotent, quota-checked, policy-validated run submission to an isolated worker.
GET /api/runs · GET /api/runs/:idTenant-scopedList tenant-visible runs and inspect run state and result.
GET /api/runs/:id/events?after=NTenant-scopedReplay sequence-numbered lifecycle events after sequence N.
POST /api/runs/:id/cancelTenant-scopedCancel queued or active work from any non-terminal state.
GET /api/approvals · POST /api/approvals/:id/decisionapprover / admin / ownerList pending tenant approvals and record approval decisions.
GET /api/artifacts/:id/downloadTenant-authorizedAuthorizes artifact metadata and returns a short-lived signed download URL.
GET /api/dashboard · GET /api/auditdashboard:read · audit:readTenant operational summary metrics and structured audit log events.
GET /api/admin/runtime-attestationadmin:runtimeRuntime security configuration attestation.
🛡️ BUILT FOR ASSURANCE

Operational controls are product features.

ATOM ships with SOC 2 readiness materials, release verification (npm run verify:release), SBOM and provenance controls, dependency audits, secret scanning, Trivy worker image CVE scanning, access-review evidence generation, and an authorized non-destructive API security smoke simulation (npm run security:pentest:smoke).

Explore Compliance Docs ↗ View GitHub Actions Gates ↗
RBAC Viewer, developer, approver, admin, and owner roles with OIDC group mapping. Enforced
Audit Structured, tenant-scoped audit events across generation, approvals, and runs. Enforced
SBOM Release supply-chain evidence and immutable SHA-256 worker digest verification. Verified
Scan Trivy worker image vulnerability checks failing on HIGH and CRITICAL CVEs. CI Gate
Quota Per-tenant run limits, daily AI token budgets, and artifact file/byte guardrails. Enforced
Replay Reconnectable event delivery and sequence de-duplication via AtomRunStream. Durable
Install & Start

Install in seconds from npm, or run locally.

Run ATOM straight from the public npm registry or GitHub Packages via @atomworld/atom, or clone the repo to run the full development profile. Execution stays disabled by default until a hardened worker image is configured.

Command Purpose
npx @atomworld/atomLaunches ATOM Workspace & Dashboard immediately on port 3001.
npm install -g @atomworld/atomInstalls the atom CLI globally and records install telemetry.
npm run devStarts Express backend (:3001) and Vite React frontend (:5173).
npm testRuns the Node unit and integration regression test suite.
npm run qa:aegisRuns the vendored Aegis self-healing Playwright SDK type-check and tests.
npm run security:pentest:smokeRuns the authorized, non-destructive API security simulation.
npm run verify:releaseChecks production configuration and immutable worker release requirements.
Quick start @atomworld/atom · v1.0.4
# Option 1: Install & run directly from npm
npx @atomworld/atom

# Or install globally and run anywhere
npm install -g @atomworld/atom
atom

# Option 2: Clone and run the local dev profile
git clone https://github.com/Samarasimhalu/Atom.git
cd Atom && npm ci
corepack enable
pnpm --dir src/frontend install --frozen-lockfile
npm run dev

# Verify live health & readiness endpoints
curl -sS http://localhost:3001/api/health
curl -sS http://localhost:3001/api/readyz