> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vikingqa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How vikingQA works

> The architecture of the platform, the path your data takes through it, and where each part runs.

vikingQA turns a plain-language description of a test into a real browser test that runs against your
application. This page explains how that happens, which components are involved, and what each one
sees. It is written for engineers and security reviewers who need to understand the system before
approving it.

If you are looking for the security controls themselves, see [Security and data protection](/security/data-protection).
For our role under GDPR, the subprocessor list and NIS2, see [Compliance and subprocessors](/security/compliance).

## The short version

You describe a test case. An AI agent opens a real Chrome browser, explores your application, and
writes a standard [Playwright](https://playwright.dev) test script. That script is then executed in
an isolated sandbox on a schedule or on demand. You get a pass or fail, with a video, a trace and
screenshots.

The important architectural point: **the agent authors the test once, and the test runs on its own
afterwards.** Routine runs are ordinary Playwright executions with no model involved.

## The lifecycle

```mermaid theme={null}
flowchart TD
    A["You describe a test case<br/>in plain language"] --> B["Agent explores your app<br/>in a real cloud browser"]
    B --> C["Agent writes a<br/>Playwright .spec.ts script"]
    C --> D["You review and accept<br/>the script"]
    D --> E["Script runs on a schedule<br/>or on demand"]
    E --> F["Results: pass/fail, video,<br/>trace, screenshots"]
    F -.->|"test breaks"| A

    style B fill:#0D9373,color:#fff
    style C fill:#0D9373,color:#fff
    style E fill:#55D799,color:#000
```

Steps 2 and 3 involve an AI model. Step 5 does not.

## Components

| Component             | What it does                                              | Where it runs          |
| --------------------- | --------------------------------------------------------- | ---------------------- |
| **Web application**   | The interface you use: test cases, results, settings      | EU                     |
| **Agent worker**      | Runs the AI agent that explores your app and writes tests | EU, Frankfurt          |
| **Realtime gateway**  | Streams the agent's progress to your browser live         | EU, Frankfurt          |
| **Database**          | Test cases, scripts, results, encrypted credentials       | Managed PostgreSQL, EU |
| **Cloud browser**     | A real Chrome instance the agent drives                   | EU                     |
| **Execution sandbox** | Runs the generated Playwright script in isolation         | EU                     |
| **Artifact storage**  | Screenshots, video, traces, logs                          | Amazon S3, EU          |
| **Browser extension** | Records a flow, or captures a manual test run             | Your own browser       |

<Note>
  Model inference is the one part that is not EU-hosted. See
  [Where your data is processed](/security/compliance#where-your-data-is-processed) for the full
  picture, including which US providers are involved and on what contractual terms.
</Note>

## How a test gets authored

```mermaid theme={null}
sequenceDiagram
    participant U as You
    participant App as Web app
    participant W as Agent worker
    participant M as Model provider
    participant B as Cloud browser
    participant Y as Your application

    U->>App: "Test that checkout works with a discount code"
    App->>W: Start an agent session
    W->>B: Open a browser
    B->>Y: Navigate, click, type
    Y-->>B: Page content
    B-->>W: Accessibility tree + screenshot
    W->>M: Page state + task
    M-->>W: Next action, or the finished script
    W-->>App: Progress, streamed live
    App-->>U: The generated Playwright script
```

Two things are worth calling out.

**The model sees your application's pages.** To write a test that clicks the right button, the agent
must read the page. It receives an accessibility tree — the structured text of the page — and
screenshots. This is the single most important fact for a privacy review, and we treat it that way
in [Testing with realistic data](/security/compliance#testing-with-realistic-data).

**The model never sees your credentials.** When the agent needs to log in, it writes a placeholder
such as `{{personas.admin.creds.web.login.password}}`. The real value is substituted immediately
before the browser action runs, and any occurrence of it is stripped out of the result before the
model or the database sees it. The agent works with credential *names*, never values.

## How a test runs afterwards

Once you accept a script, it is an ordinary Playwright test. Running it involves no AI model at all:

```mermaid theme={null}
flowchart LR
    S["Schedule or<br/>manual trigger"] --> R["Isolated sandbox<br/>starts"]
    R --> P["Playwright script<br/>executes"]
    P --> Y["Your application"]
    Y --> P
    P --> A["Video, trace,<br/>screenshots, logs"]
    A --> D["Results in<br/>the web app"]

    style R fill:#0D9373,color:#fff
```

Each run gets its own sandbox. Sandboxes are never shared between organisations and never reused
across customers. When a run finishes, or after an idle timeout, the sandbox is destroyed.

## Reaching your application

Most customers point vikingQA at a staging or test environment on the public internet. Nothing
special is required.

If your environment sits behind an IP allowlist, you can enable **fixed-IP egress**. Every browser
session and test run for your project then leaves from a single static address that you add to your
firewall. If we cannot determine the correct egress configuration for a session, the run fails
rather than silently falling back to a shared dynamic address — so an allowlisted environment is
never reached from an unexpected IP.

## The browser extension

The extension is optional. It does two things:

* **Record a flow** in your own browser and turn it into a test case, so the agent starts from a real
  user journey instead of exploring blind.
* **Capture a manual test run**, recording the tab video, console output and network activity while a
  human tests by hand.

It only records on URLs your project administrator has added to an allowlist, enforced both in the
browser and again on our server. Passwords, one-time codes, card numbers and API keys are stripped
inside your browser *before* anything is transmitted, and recording refuses to start if that
sanitiser fails its own start-up self-test.

## Design decisions that matter for review

**Tenancy is enforced before application code runs.** Every request passes through middleware that
validates organisation membership, project access and role from a signed token. A request that fails
any of those checks never reaches a handler.

**Credentials are encrypted with a key the agent does not hold.** Customer application logins are
encrypted with AES-256-GCM under a key held only by the web application. The agent worker holds a
different key for a different purpose and cannot decrypt your logins.

**The generated artefact is standard Playwright.** There is no proprietary format and no lock-in.
You can read the script, edit it, and take it with you.

**The agent runs against your test environment, not your production system.** This is a
recommendation, not a technical restriction — and it is the single most effective privacy control
available to you. We explain why in [Testing with realistic data](/security/compliance#testing-with-realistic-data).