AgentOps Argus is a QA platform. You write tests as small YAML files, build and debug them on a visual canvas in the desktop app, run them on your own machine or headless in GitLab CI, and keep their results, test cases, cycles, requirements and defects in a web server that replaces QMetry. An AI assistant (Claude Code, Codex or Gemini CLI) works inside the desktop app and through an MCP server, so it can write, run and triage tests with you.

This manual covers every part of Argus as it is built today, from installing the desktop app to running the web server for a team.

1.1 The pieces

All of them run the same engine (argus-runner), so a test behaves the same on a laptop, in a pipeline and when the assistant runs it.

1.2 How the pieces fit

• The tests repository is the source of truth for automation. Tests, flows, payloads, data files and argus.yaml live in git. The desktop app and the assistant edit those files; nothing about a test's steps is hidden in a database.
• The server is the source of truth for test management. Manual test cases, cycles, executions, requirements, releases and defects live in argus-server. Automated results reach it from the CLI and from CI. argus sync sends each test's flow to the server so the web app can draw it.
• Secrets never live in YAML. argus.yaml names variables (${QA2_PASSWORD}), OS keychain items (${keychain:…}) or Azure Key Vault secrets (${keyvault:…}). On a desktop they come from local variables; in CI from masked CI/CD variables. Every secret is masked as •••••• in every result, log, report and evidence file.

1.3 Words used in this manual

1.4 What you need

1.5 How this manual is organised

The chapters follow the work: install, open a project, write tests, connect them to systems, run them, then share results and manage releases on the server. Each chapter is complete on its own and links to the others; the reference chapters at the end list every command, environment variable, file and keyboard shortcut.

Throughout the manual:

• ⌘ means Ctrl on Windows and Linux, and Cmd on macOS. ⇧ is Shift, ⌥ is Alt / Option.
• Paths such as argus-results/ are relative to the project folder.
• Screenshots come from the real app, mostly in the dark theme; the light theme (⇧⌘L) looks the same in light colours.

2.1 Windows: the one-line install

AgentOps Argus is installed the same way as AgentOps: one line in PowerShell, from the update server at agentops.build.

irm https://agentops.build/argus/install.ps1 | iex

The script downloads AgentOpsArgus-<version>-windows-x64-setup.exe into C:\InternalApps\AgentOpsArgus, checks it against its published .sha256 and opens the installer. The installer needs no administrator rights and installs to %LOCALAPPDATA%\Programs\AgentOpsArgus:

Install and uninstall ask you to close running copies from the install folder first.

Options for the script (environment variables, set before the irm line):

irm | iex cannot pass parameters; to pass -Silent use the scriptblock form:

& ([scriptblock]::Create((irm https://agentops.build/argus/install.ps1))) -Silent

A portable ZIP with the same files is published next to the installer: extract it anywhere and run argus-desktop.exe.

2.2 Updates

The desktop app checks its update feed about 20 seconds after it starts and then every 6 hours. When a newer version is published it asks once per version:

• Download and install downloads the installer to the app's data folder, checks its SHA-256, quits the app and runs the installer silently. Setup closes whatever still runs from the install folder, installs and starts the new version.
• Later leaves an Update to x.y.z chip in the status bar.

The version chip at the right end of the status bar, or Check for updates in the command palette (⌘K), checks now.

On Linux and macOS the dialog opens the download page instead of installing.

Behind Netskope or another TLS-inspecting proxy

Every connection the app and argus make (sign-in, the Argus server, Jira, GitLab, updates, http steps, the API explorer) goes over SChannel on Windows, so it trusts what your browser and PowerShell trust (the Windows certificate store, where IT normally places Netskope's CA). It also trusts every PEM file it finds in the places AgentOps uses:

1. ARGUS_CA_CERTS (;-separated files), NODE_EXTRA_CA_CERTS, SSL_CERT_FILE
2. ~/.argus/certificates/*.pem
3. ~/.agentops/certificates/netskope.pem (AgentOps' Install Certificate writes it)
4. certificates/netskope.pem next to the app (the installer puts it there)

The install script retries a failed HTTPS download trusting the same files.

Proxies

Argus uses the proxy your browser uses. In order:

1. localhost and 127.0.0.1 always go direct.
2. ARGUS_PROXY: direct skips every proxy, system uses only the Windows settings (ignoring HTTPS_PROXY), a URL (http://host:port, optionally http://user:password@host:port) is the proxy to use.
3. NO_PROXY hosts go direct; then HTTPS_PROXY / HTTP_PROXY / ALL_PROXY.
4. On Windows, the system settings: the PAC script from Internet Options or WPAD auto-detect (evaluated like Edge does), else the manual proxy and its bypass list.

A proxy that wants a Windows (NTLM/Kerberos) sign-in is not supported; put a user and password in ARGUS_PROXY, or ask IT to let Argus through.

When a connection fails, the message says which part failed (DNS lookup, could not connect, TLS certificate not trusted, proxy failed, timed out), the system's own words for it, the route it took (direct or through proxy … and where that proxy came from), and what to do. For example:

TRACIntermodal sign-in: https://identity-qa.example.com/connect/deviceauthorization:
TLS certificate not trusted (Connection Failed: tls connection init failed: invalid
peer certificate: UnknownIssuer), going direct (no proxy set). This network may be
intercepting HTTPS (Netskope). Put its CA certificate in …

Where the feed comes from

For an internal server the feed is the install script itself: the app reads its $DefaultVersion = '…' line (it never runs the script). Either way the installer must match its published SHA-256 before it runs.

2.3 Publishing a release (for maintainers)

Releases go to the update server (a Cloudflare Worker behind https://agentops.build/argus, in packaging/update-server/). On Windows, with the server's admin token:

$env:ARGUS_RELEASE_TOKEN = '<ADMIN_TOKEN>'
scripts\publish-argus.ps1 -Sign -Release -Notes 'Data sets on steps'   # patch bump, signed build, upload, release

Every installed app, and every irm https://agentops.build/argus/install.ps1 from then on, gets the released version. packaging/update-server/README.md covers deploying the server and each step of a release.

To publish to an internal download server instead:

$env:VERSION = '0.1.42'; .\scripts\build-windows.ps1 -Package     # dist\AgentOpsArgus-0.1.42-windows-x64-setup.exe + portable.zip
.\packaging\windows\publish-internal.ps1 -Version 0.1.42 -Destination \\10.84.96.75\agentops\downloads

publish-internal.ps1 copies the installer, ZIP and checksums to the served folder, then writes the install script with $DefaultVersion stamped. The script goes last, so clients only see a version once its installer is in place.

In GitLab, packaging/gitlab/windows-release.gitlab-ci.yml (included from the root .gitlab-ci.yml) builds on a Windows runner tagged windows (ARGUS_WINDOWS_RUNNER_TAG) and publishes to agentops.build: automatically for a vX.Y.Z tag, by hand from a default-branch pipeline, or with ARGUS_RELEASE=1. Set a masked ARGUS_RELEASE_TOKEN (the server's admin token) and ARGUS_SIGN=1 with the signing variables in the project's CI/CD variables. A tag pipeline uploads and releases; any other pipeline only uploads, unless ARGUS_PUBLISH_RELEASE=1. A release needs a signed installer. Without a tag or VERSION, a build's version is Cargo.toml's <major>.<minor> with the pipeline number as the patch.

It needs Windows x64, Rust with the MSVC toolchain, the Visual Studio C++ Build Tools and NSIS 3.08 or later (winget install NSIS.NSIS). The packages are built with a static C runtime, so target machines need no Visual C++ redistributable.

2.4 Linux and macOS: building from source

The repository pins its Rust version in rust-toolchain.toml. On Linux, GPUI needs the X11/Wayland and font headers:

sudo apt-get install libxkbcommon-dev libxkbcommon-x11-dev libxcb1-dev \
  libfreetype-dev libfontconfig-dev libwayland-dev libvulkan-dev

cargo build --release -p argus-cli -p argus-desktop -p argus-server
./target/release/argus-desktop path/to/tests       # open a project folder at start

The desktop app and its UI crates are workspace members but not default ones, so plain cargo build / cargo test skip them; name them with -p or use --all.

2.5 First start

Start AgentOps Argus from the Start menu (or argus-desktop [folder]). The welcome screen lists your recent projects and other ways to start:

• Open folder… (⌘O), or drop a folder on the window: open a folder of tests (the one with argus.yaml). See chapter 3.
• Recent projects show their branch, last result and when they last ran. Pin a project to keep it on top (pinned ones survive Clear); remove one with its × button. Up to 12 unpinned projects are kept.
• Try the sample suite opens examples/local, which runs with no network.
• Import a Robot Framework project… and Import with the assistant… (see chapter 15).
• Record a browser test… (see chapter 5).
• API explorer (⌘4) and Repository (⌘5) work without a project.
• Sign in… connects the app to an argus-server (below).

2.6 Signing in to argus-server

The desktop app works fully without a server. Signing in adds server runs in the run view, defects filed in Argus (and Jira through it), and cycles for the assistant's test-management tools.

1. Open the account menu (the person icon at the bottom of the rail) or Sign in to argus-server… in the palette.
2. Set the server address under Argus-server → Change. It is kept as the ARGUS_URL local variable, which wins over an ARGUS_URL environment variable.
3. Click Sign in. When the server has single sign-on (Duende IdentityServer, Entra ID or another OpenID Connect provider) the app shows a code and opens the provider's device page; enter the code there.

The refresh token is kept in the OS keychain (service argus, account login:<server>), never in a file. Without single sign-on, paste a personal token from the web app's My tokens page; it is kept as the ARGUS_TOKEN local variable.

Set ARGUS_PROJECT for the folder (Connections → Variables → This project, or the palette's Set this folder's Argus project…) so runs and defects land in the right server project.

The CLI signs in the same way:

argus login --server https://argus.example.com    # shows a code for the provider's device page
argus logout --server https://argus.example.com

2.7 Where things are kept

2.8 Graphics and remote desktops

Without a GPU on Windows (the software adapter of many VMs) and in a Remote Desktop session, the window draws in low-power mode, as AgentOps does: at most 30 frames a second when a redraw is needed, no blurred shadows, no decorative animations or blinking carets. ARGUS_LOW_POWER=1 forces this mode on, ARGUS_LOW_POWER=0 turns the frame limit off. ARGUS_THEME=light starts in the light theme.

3.1 What a project is

An Argus project is a folder (usually a git repository) with an argus.yaml at its root and test files below it. Everything Argus needs to run a test is in that folder or named by it.

orders-tests/
├── argus.yaml                 # environments, connections, MCP servers, masking, timeout, workers
├── tests/
│   ├── orders/
│   │   ├── create-order.yaml        # kind: test (the default)
│   │   └── create-order.layout.json # canvas positions (written by the desktop app)
│   └── nightly-digest.yaml          # kind: automation
├── flows/
│   └── login.yaml             # kind: flow, called with sub-flow or setup:
├── payloads/
│   └── orders/create.json     # {{payload.orders/create}}
├── data/
│   └── skus.csv               # data: data/skus.csv
├── e2e/checkout.spec.ts       # Playwright specs a playwright step runs
├── robot/…                    # Robot suites a robot step runs
├── package.json               # @playwright/test, when you have UI tests
└── argus-results/             # written by runs — add it to .gitignore

Rules Argus follows when it looks for tests:

• Every .yaml / .yml file that parses as a test, flow or automation is one. One test per file; file names in kebab-case.
• The nearest argus.yaml above a test applies to it.
• Hidden folders (.robot, .git), node_modules and argus-results/ are skipped.
• A folder holding a file named .argusignore is skipped, with everything in it. Migrated application copies get one, so their CI and compose YAML are never read as tests.
• payloads/ beside argus.yaml is the payload library, not tests.

3.2 Opening a project in the desktop app

• Open folder… on the welcome screen, ⌘O, or drop a folder on the window.
• From a terminal: argus-desktop path/to/tests.
• The folder menu (the folder name at the top left) switches projects and holds folder-wide commands: Set up GitLab CI/CD…, Migrate an application from another folder…, Upgrade this project to Argus in place….

Opening a folder parses it in the background; the previous project stays usable until the new one is ready. The app watches the folder, so tests that change on disk (a git pull, an edit in another editor, the assistant) reload by themselves; the explorer's Refresh button and Reload tests from disk in the palette force it.

3.3 argus.yaml

timeout: 45s                     # default step timeout (else 30s)
workers: 4                       # tests at once for argus run (auto = one per CPU; else 1)

environments:
  qa2:
    vars:                        # read in tests as {{env.<name>}}
      api: https://qa2.example.com/api
      web: https://qa2.example.com
      user: qa-bot
      password: "${QA2_PASSWORD}"          # a process / CI / local variable
    connections:                 # only this environment (wins over shared ones)
      orders-db: { type: postgres, url: "${QA2_PG_URL}" }
    mcp:
      servers:
        orders: { type: http, url: https://orders-mcp.qa2.example.com/mcp, headers: { Authorization: "Bearer ${ORDERS_MCP_TOKEN}" } }
  uat:
    vars:
      api: https://uat.example.com/api
      web: https://uat.example.com

connections:                     # shared by every environment
  batch-host: { type: ssh, host: batch01.qa, user: qa, key: "${BATCH_SSH_KEY}" }

mcp:
  config: mcp.json               # an mcpServers file (Claude Code / Cursor format)
  servers:                       # or inline, same format; these win
    servicebus: { command: npx, args: [-y, "@acme/servicebus-mcp@1.4.2"] }

mask:
  fields: [ssn, card_number]     # JSON keys masked anywhere in results
  patterns: ['\b\d{3}-\d{2}-\d{4}\b']
  allow: [QA_API_URL]            # ${NAME}s that are not secret

Unknown keys are errors, so a typo is caught by argus validate instead of being ignored.

A test picks its environment with env: in the test, --env on the command line (which wins), or the desktop's environment menu in the top bar.

3.4 Project settings screen

The desktop's Project settings (the gear in the rail, ⌘7) edits argus.yaml as a form and as YAML, side by side or one at a time. Both views edit the same text: a change in the form appears in the YAML at once, and YAML you type refills the form as soon as it parses.

The form covers the default step timeout, workers, environments (add, rename, remove) with their variables and per-environment MCP file, the shared MCP file, and masking (fields, patterns and allowed names, one per line). Connections and inline MCP servers are listed there and edited on the Connections screen or in the YAML view.

Edits keep your comments, key order and formatting: only the keys you changed are rewritten. Nothing is saved until Save (⌘S); Revert reloads the file. If the file changed on disk while you were editing, a banner offers Load the file or Keep mine and save. Keys the runner would reject are flagged before you save.

3.5 Values and secrets

Values in argus.yaml can read secrets from four places. Write them as a whole value or inside a string:

A missing secret's error names every place it looked.

{{env.NAME}} without an environment

A test may read {{env.NAME}} for a name no argus.yaml environment defines. Argus then reads the variable NAME directly (a local variable on the desktop, a CI/CD variable in a pipeline), masked unless mask.allow lists it. This is how migrated applications get their settings and how a project with no environments still reads a password.

3.6 Local variables (desktop)

In a pipeline, ${NAME} comes from the job's CI/CD variables. On your workstation the same names are local variables, set on the Connections screen's Variables tab (or the palette's Set a local environment variable…).

• Plain values are kept in local-env.json in the desktop's data folder; secret values in the OS keychain as local-env.<NAME>. Neither is ever in the repository.
• Every run started from the app sees them as environment variables: ${NAME} in argus.yaml, process.env.NAME in Playwright, %{NAME} in Robot, scripts, {{env.NAME}}, and the assistant's argus mcp. The app's terminal gets them too.
• They win over a variable of the same name the app was started with.
• Secret ones are masked in results.
• The tab starts with a callout listing the ${NAME}s argus.yaml reads that nothing sets yet; click one to set it.

This project or All projects

Each variable applies to either All projects or This project only (the open folder). In that folder its own value wins over the one for all projects; the overridden value is shown struck through. Other folders don't see it. A folder's secrets are keychain items local-env.<NAME>.<hash of the folder>.

ARGUS_PROJECT (the argus-server project key) and GITLAB_PROJECT_ID start as This project variables, since each tests repository has its own Argus project: use Set ARGUS_PROJECT for this folder on the tab, or the palette's Set this folder's Argus project….

The plain argus CLI outside the app reads only its shell's environment; set the same names there (or in CI) for command-line runs.

3.7 Masking

Secrets never reach output.json, events.ndjson, junit.xml, the report or text evidence. Argus replaces with ••••••:

• every value argus.yaml reads through ${...} (environment variables, connections, MCP servers), and secret local variables;
• literal values under a connection's password, key, token, secret, headers or env, and an inline kubeconfig;
• each of those in its URL-encoded form too;
• any user:pass@ in a URL;
• JSON fields named password, secret, client_secret, api_key or private_key;
• tokens an HTTP step's auth: signs in with;
• whatever mask.fields and mask.patterns add.

Text evidence files up to 200 MB are masked (above 16 MB one line at a time); a larger one is left as it is, with a warning in the run's output. The report's Copy as cURL turns masked credential headers into shell variables such as ${AUTHORIZATION}, so a copied command never carries a secret.

3.8 Checking a project

argus validate tests/ --env qa2      # schema, references, and every environment/connection/MCP server named
argus check --env qa2                # reach each connection, MCP server and base URL
argus check --env qa2 --name orders-db

validate checks every test's schema, required fields per step type, durations, every {{steps.x}} reference and transform name, and that every environment, connection and MCP server a test names exists. check goes further and connects: SELECT 1 on databases, true over SSH, the cluster version for AKS, MCP initialize and tools/list, PING on Redis, and a GET on the environment's http(s) variables. Both exit 2 on a problem.

In the desktop app the breadcrumb bar shows Valid · 0 issues for the open test (or the count, with the problems listed), and the Connections screen's Test button runs the same checks as argus check.

The window has five parts:

1. Top bar: the folder menu, the command palette search, the environment menu, the assistant button and the run buttons.
2. Rail (left edge): one button per screen.
3. Main area: the explorer and canvas, or the screen the rail picked.
4. Side panel (right): the step Inspector and the Assistant.
5. Status bar (bottom): what is running, the terminal, the server and the version.

Watch the video: Desktop 1: Getting started 1:34

4.1 Top bar

Under the top bar, the breadcrumb bar shows where the open test lives (local › flows › TC-0001), its title, its validation state (Valid · 0 issues, or the problems) and the Author / Run view switch.

4.2 The rail

4.3 Explorer

The explorer lists the project's tests, flows and automations as a folder tree, each with its last result.

• Filter box: words match a file name, id, title or tag; tag:smoke keeps tests with that tag; status:fail keeps tests whose last result failed. Words combine: orders tag:smoke status:fail.
• Collapse all / Expand all buttons beside the filter (handy with thousands of tests).
• New test (file-plus icon) creates a test in the selected folder from a template; New automation (lightning icon) creates an automation (chapter 11).
• Run N runs every test in the selected folder (⇧⌘↵). Folder runs leave automations out.
• Refresh reloads the folder from disk.
• Marks: auto for automations, a clock for anything with an enabled trigger.
• Right-click a row: Move to…, Rename… (F2), Show in Files, Copy relative path, Delete….
• Drag a test or folder onto a folder to move it (5.8).
• Select a row and press Delete (or ⌘⌫) to delete it, after a confirmation that lists the tests that use it.

The explorer, the side panel and the evidence drawer are resizable: drag their edges. Sizes are saved. ⌥⌘B collapses or opens the side panel; its expand button widens it over the canvas.

4.4 The command palette (⌘K)

The palette searches everything the window can open: tests (by id or title), their steps, kept local runs and server runs, connections, and every command. Type a few letters and press Enter.

Some commands only live in the palette (or a menu), for example:

4.5 Side panel: Inspector and Assistant

The side panel has two tabs:

• Inspector: with no step selected, the test's settings (id, title, tags, data, timeout, requirements, triggers); with a step selected, that step's settings in tabs (Config, Data, Behavior, …) and a composer made for its type. See 5.4.
• Assistant: the AI chat (chapter 13).

The panel can be resized, expanded over the canvas, or collapsed to a strip.

4.6 Status bar

From left to right: the run state (LOCAL, or the GitLab pipeline being followed), the project's folder and git branch, runner idle or what is running, Terminal, the argus-server you are signed in to (or no argus-server), and the version chip (click it to check for updates).

4.7 Terminal

Ctrl+` opens a terminal under the workspace, full width. Shells start in the open project folder with your local variables set, so argus run, npx playwright test or robot behave as runs from the app do. On Windows the shell is PowerShell (pwsh.exe, else powershell.exe) through ConPTY.

Drag the panel's top edge to resize it; the height is saved.

Watch the video: Desktop 7: Files, terminal and git 0:53

4.8 Files

The Files screen (⌘6) shows the project folder as a tree beside a code editor, like an IDE's project view. Use it for Playwright specs, Robot suites, Python, data files, payloads and anything else in the repository.

The tree

• Click a file to open it in an editor tab. Right-click for New file, New folder, Rename (F2), Delete, Cut / Copy / Paste / Duplicate, Move to…, Open preview, Open in browser, Open with default app, Convert to Argus steps… (Robot files), Convert to Playwright TypeScript (pytest files), git history, blame and changes, and … with the assistant.
• Pick several rows with Ctrl/Shift-click or Shift+arrows; copy (⌘C), cut (⌘X) and paste (⌘V) work with your system's file manager too. Pasting an image from the clipboard saves it as pasted image <date>.png.
• The search box finds files by name anywhere under the folder (ext:, type: and size: filters work). In files (⇧⌘F) searches file contents, with globs to include or exclude and Replace all; Find in folder scopes it to one folder. Click a hit to open the file at the line.
• Expand all opens up to 400 folders; Collapse all closes them.
• Git changes mark the rows. The tree updates by itself when files change (a folder watcher, not polling).
• Drag a file or folder onto a folder to move it; references in tests follow.

The editor

• Highlighting for YAML, JSON, TypeScript/JavaScript, Python, SQL, shell, Robot Framework and more; line numbers, indent guides, folding.
• Ctrl+F find, Ctrl+H (⌘⇧F on macOS) replace, Ctrl+G go to line, Alt+Z word wrap, Ctrl+S save, Ctrl+W close, Ctrl+Shift+T reopen.
• Autocomplete (Ctrl+Space): Robot sections, settings, BuiltIn and library keywords and your project's own keywords; the Playwright API in TypeScript; Python keywords; Argus YAML keys, step types, {{steps.<id>}} references and transforms after |.
• Format document (Shift+Alt+F, or the Format button): Prettier for TS/JS/JSON (from node_modules/.bin, then PATH; Argus's own JSON formatter when Prettier is missing), Ruff then Black for Python, Robocop format then Robotidy for Robot. Connections → Tools on this computer can install them.
• Open as test opens an Argus test in the test editor.
• CSV files, JSON lists and YAML lists under data/ have a Table view: edit cells (Tab / Shift+Tab, Enter moves down, Escape reverts), then save.
• Previews: images (with Copy image), PDFs (rendered in the app), HTML and SVG (a Source / Preview switch). Text files over 5 MB open in a read-only big-file viewer (up to 1 GB), for logs.
• Tab right-click menu: close others / left / right / saved / all, reopen, save, copy path, show in tree.

Folder view opens a two-pane explorer (sizes, dates, preview) on the same folder.

4.9 API explorer

The API explorer (⌘4) is a full API workbench (ported from Switchyard): projects, collections and environments of HTTP, GraphQL, gRPC and WebSocket requests, with scripts, tests, runs and import/export. Its data lives in the desktop's data folder, not in the tests repository. {{vault.name}} reads the OS keychain item name.

• Its AI buttons ask the assistant panel beside it.
• Requests the assistant writes in ```http blocks get an Open in the API explorer button.
• An HTTP step's composer can copy a saved request in with From API explorer… (6.1).
• Inside it, ⌘1–⌘8 switch the explorer's own pages; use the rail or ⌘K to leave.

4.10 Repository

The Repository screen (⌘5) is a git client for the open folder's repository: the commit graph, diffs, local changes and staging, branches, tags, stashes, remotes, git-flow, bisect, LFS, accounts (GitHub, GitLab, Azure DevOps) and pull requests, with its own assistant. Events in .gitignored paths are ignored, so a run writing argus-results/ doesn't make it busy.

4.11 Copying text

Text in the side panel, the run view, the evidence drawer, logs, the Robot keyword tree, the YAML view, the assistant's replies and the Connections screen can be selected with the mouse (drag, double-click a word, triple-click a line) and copied with ⌘C, or with right-click → Copy.

4.12 Keyboard shortcuts at a glance

The full list is in chapter 22.

4.13 Closing the window: Argus keeps running in the tray

Closing the window does not quit Argus. The window goes away and Argus keeps running behind its icon (the watcher's eye) in the tray, so the open project's schedules and intervals keep firing (11.4), runs in progress finish, and the assistant keeps working. The first time in a session a notification says AgentOps Argus is still running; click it to bring the window back.

The tray icon is in the Windows notification area (it may sit under the ^ arrow at first; drag it onto the taskbar to keep it in sight), the macOS menu bar, and on Linux any desktop that shows status icons (KDE and most others; GNOME needs the AppIndicator extension).

Only one Argus runs at a time. Starting it again (Start menu, desktop shortcut, argus-desktop) while it sits in the tray shows the window it already has instead of starting a second copy that would fire the same schedules twice. argus-desktop <folder> opens that folder there; argus-desktop --quit quits the running Argus.

To make closing the window quit Argus as before, run Keep running in the tray when the window is closed from the palette (⌘K); run it again to turn it back on. It is kept as keep_running in desktop.json ("off"), and ARGUS_KEEP_RUNNING=0 turns it off for one start. With it off, every start is its own copy. The palette also has Pause or resume all schedules in this app and Quit AgentOps Argus.

A test is one YAML file. The desktop app gives you three ways to edit it, all on the same text: the canvas (cards you click and drag), the YAML view (the file itself) and the inspector (a form for the selected step). Every change in one shows in the others at once, and edits keep your comments and formatting.

Watch the video: Desktop 2: Building a test on the canvas 1:28

5.1 Anatomy of a test

id: TC-1042                       # unique key: results, Jira links and argus-server use it
title: Approved order gets an invoice
tags: [smoke, orders]             # --tags smoke,!slow selects by them; `serial` = never in parallel
priority: high
requirements: [EBM-412]           # the stories this test proves
folder: orders                    # grouping in argus-server
env: qa2                          # default environment (--env wins)
timeout: 45s                      # default step timeout for this test
setup: { use: flows/login, with: { user: "{{env.user}}" } }   # a flow run first
data: data/orders.csv             # optional: run the whole test once per row

steps:
  - id: create
    type: http
    request:
      method: POST
      url: "{{env.api}}/orders"
      json: "{{payload.orders/create}}"
    expect: [ "status == 201", "body.id" ]

  - id: invoice
    type: sql
    connection: orders-db
    query: SELECT id, total FROM invoices WHERE order_id = :id
    params: { id: "{{steps.create.body.id}}" }
    retry: { until: "count == 1", every: 2s, max: 30s }

  - id: totals-match
    type: assert
    expect: [ "steps.invoice.row.total == steps.create.body.total" ]

Every step has an id (unique in the whole test, nested steps included) and a type, plus these optional fields:

Every step type and its fields are in chapter 6.

5.2 Creating a test

• Explorer → New test (file-plus icon) creates TC-<next> in the selected folder from a template and opens it. The palette has New test in the selected folder.
• New automation (lightning icon) does the same for an automation.
• Record a browser test (5.9) writes a test from what you do in a browser.
• Ask the assistant: "write a test that creates an order and checks the invoice" (chapter 13).
• Write the YAML in any editor; the app picks the file up from disk.

5.3 The canvas

The canvas draws the test as a flow of cards, top to bottom. Each card shows the step's type badge (HTTP, SQL, SH, ASRT …), its id, a one-line summary (POST /orders, the query, the command) and its assertions. During and after a run, each card shows its status: running (with elapsed time and the current action), passed, failed, skipped.

Views. The switch above the canvas picks Canvas, Split (canvas and YAML side by side) or YAML. ⌘\ cycles them. In Split view, drag the divider to give either side more room; double-click it to reset. The width is saved.

Data lines. With Data lines on, dotted lines connect each step to the steps whose data it reads ({{steps.onHand.available}}), labelled with the field. It shows at a glance where each value comes from.

Navigating.

Adding steps. Press / (or click the + between two cards) to open the step palette, then type to filter or click a chip. Steps are grouped:

The new step starts from a working template with a fresh id (call, query, …) and is selected so you can fill it in.

Control flow is drawn as structure: a branch splits into then and else lanes, a loop is a container of its steps, poll-until wraps the step it polls, and sub-flow / setup cards fold their flow's steps (5.6).

5.4 The inspector

Select a card to edit it in the side panel's Inspector. With no step selected, the inspector shows the test's settings: id, title, tags, data, timeout, requirements and the Triggers section.

A step's settings are split into tabs:

Fields save to the YAML when they lose focus (Enter, or ⌘↵ in multi-line fields). Mappings are YAML ({ key: value }); fields that hold JSON (an HTTP json body, Kafka values, Redis set values, MCP args) are a JSON editor with a Valid / Not valid bar (click it to jump to the problem), Format and Compact, and Shift+Alt+F.

A step's connection field lists the connections of the right type. Every field that takes a value has {x} Insert value, and a lens under it shows where each {{...}} comes from and what it was on the last run (7.7).

Renaming a step. Every step's Config tab starts with its id, the name on its card (the HTTP composer shows it above the URL bar). Type a new one and press Enter: the test's references to the step follow ({{steps.<id>...}} in any field, expect checks, auth: { use: <id> }), and so does the card's place on the canvas. An id another step already has, or one with spaces or dots, is refused.

⌘Z undoes and ⇧⌘Z / ⌘Y redoes any change, from the canvas, the inspector or the YAML view.

5.5 The YAML view

The YAML view shows the file with line numbers that stay put while it scrolls sideways. Click Edit YAML to edit it in a code editor (no soft wrap, highlighting, line numbers). The canvas and inspector follow as soon as the text parses; problems show in the breadcrumb bar's validation chip.

5.6 Flows, sub-flows and setup

A flow is a reusable piece of a test: signing in, creating a customer, cleaning up. It is a file with kind: flow:

# flows/login.yaml
kind: flow
id: FLOW-LOGIN
title: Sign in and return a token
steps:
  - id: token
    type: http
    request:
      method: POST
      url: "{{env.api}}/auth/token"
      json: { user: "{{vars.user}}", password: "{{vars.password}}" }
    expect: [ "status == 200", "body.token" ]

Use it in a test as a step, or as the test's setup:

setup: { use: flows/login, with: { user: "{{env.user}}", password: "{{env.password}}" } }
steps:
  - id: login
    type: sub-flow
    use: flows/login                 # .yaml optional; from the argus.yaml folder or beside the test
    with: { user: "{{env.user}}", password: "{{env.password}}" }
  - id: me
    type: http
    request:
      url: "{{env.api}}/me"
      headers: { Authorization: "Bearer {{steps.login.token.body.token}}" }

• The flow sees env, the data row and its with values as {{vars.*}}, not the caller's steps.
• The caller reads the flow's steps as {{steps.<sub-flow id>.<inner id>…}}.
• Flows may nest (not recursively).
• A flow only runs through a test; argus run never runs it on its own.

On the canvas, sub-flow and setup cards start folded: they show "N steps", and while running the elapsed time and the inner step running. Click the chevron to open the card and see the flow's steps (read-only, live during a run, clickable to see each step's result in the drawer). The palette has Collapse / Expand all flow cards on the canvas. Which cards are open is kept on your machine, not in the repository.

5.7 Selecting, copying and pasting steps

A bar at the bottom of the canvas shows how many steps are picked, with Copy, Duplicate, Auto layout, Delete and Clear. Right-click a card for Copy / Paste / Duplicate / Delete; right-click empty canvas to paste at the end.

Pasting into another test puts the steps after the selected step (or at the end), in one undoable change:

• Ids that already exist get _2, _3 …, and references between the pasted steps ({{steps.<old>…}}, expect paths, auth: { use: … }) follow.
• File references (use:, data:, specs, scripts, payload files) are rewritten for the new folder.
• References to steps the target test doesn't have are listed in a toast, and those cards show red until you fix them.

The clipboard holds plain YAML (a list of steps), so you can also paste steps from a text editor, or copy them out into one.

5.8 Moving, renaming and deleting tests

Move a test, flow or folder by dragging it in the explorer onto a folder (onto a test: into its folder; below the rows: to the top), or right-click → Move to… and pick a folder or type a new one (flows/shared). The Files tree moves any file the same way.

References that would break are rewritten: use: flows, data: files and the files steps name (scripts, specs, suites, payloads) in the moved tests and in every test that reads a moved file. The canvas layout moves with its test, and the open test and editor tabs follow. Commands inside run: text, argus.yaml, CI paths and Robot/Playwright imports are not rewritten.

Rename a test, flow or folder with right-click → Rename… or F2 on the selected explorer row. The name turns into a text box; type the new name and press Enter (Esc keeps the old one). Typing a name without .yaml keeps the extension. The same references are rewritten as for a move, the canvas layout file is renamed with its test, and the open test and editor tabs follow. Renaming in the Files tree (F2) rewrites them too. Renaming is refused while a run is live, or when the folder already has that name.

Delete with right-click → Delete… or the Delete key on a selected explorer row. The confirmation lists the tests that use what you are deleting (a flow other tests call, a data file); the test's .layout.json goes with it. Deleting is refused while a run is live.

5.9 Recording a browser test

Record a browser test… (palette, or the welcome screen) opens Chrome or Edge on an address, in its own window and a throwaway profile. Use the application; each click, typing, checkbox, select and key is recorded as you go, shown with the Playwright locator it will use (also on hover, in the page).

• Assert visible, Assert text and Assert value make your next click a check instead of an action. Visual check adds a screenshot checkpoint (snapshot(page, 'checkpoint 1')) that later runs compare with its baseline (see 9.13).
• Each recorded element also keeps up to four backup locators and a fingerprint (its role, name, label, text, id, test id, classes). The spec calls heal(page, …) for it, so a run can still find the element after a UI change and propose the new locator for review.
• Typing becomes one fill; navigations the page caused itself are not recorded; pop-ups follow the click that opened them.
• Passwords are never written down: the spec reads ARGUS_PASSWORD, which the step maps to the environment's password var.
• Save as new test writes a Playwright spec with one test.step per action (so the run view and report list each action as a step) and an Argus test with a playwright step. Add to open test appends the step to the open test.
• Without a package.json naming @playwright/test, one is written at the tests folder's root; run npm install and npx playwright install chromium once.

ARGUS_BROWSER picks the browser program; otherwise Chrome, Edge, Chromium, then Playwright's own Chromium are looked for.

5.10 What the assistant changed

When the assistant edits the open test, a banner Changed by the assistant marks new and changed cards with Undo and Keep. Each assistant reply also lists the files it changed, with a diff and Undo per file or for the whole reply (chapter 13).

5.11 Validation as you type

The breadcrumb chip shows Valid · 0 issues or the number of problems; click it to list them. Cards with a problem show red. Validation covers the schema, required fields per type, durations, {{steps.x}} references (unknown steps, later steps), unknown transforms, :name SQL parameters with no value, missing payloads and unknown connections or MCP servers for the selected environment. argus validate runs the same checks on the command line.

5.12 Committing and merge requests

Commit changed tests and open a merge request… (palette, or the Repository screen for full git) puts the changed test files on a branch, pushes it and opens a GitLab merge request. It needs GITLAB_URL, GITLAB_TOKEN (api scope) and GITLAB_PROJECT_ID (else the origin remote's project path) as local variables. A branch other than the checked-out one is committed through a private index, so your checkout and other edits stay as they are. GITLAB_TARGET_BRANCH overrides the target (else the project's default branch).

Argus has 23 step types. This chapter lists each one: what it does, its YAML, its output (what later steps read as {{steps.<id>.…}} and what its own expect reads as bare paths), and what the desktop's inspector offers for it.

Two rules hold for every type:

• A step fails when it fails to run or any expect fails. An infrastructure error (an unreachable host, a refused sign-in, a missing program such as robot or npx) is reported separately from a test failure, and makes argus run exit 2 rather than 1.
• Secret-looking values (credential headers, passwords, tokens, anything from ${...}) are masked in the step's output and evidence.

6.1 http

Calls an HTTP API.

- id: create
  type: http
  request:
    method: POST                 # default GET
    url: "{{env.api}}/orders"    # required
    headers: { X-Request-Id: "{{now}}" }
    query: { page: 1 }           # added to the URL, encoded
    json: { sku: A1, qty: 2 }    # or json: "{{payload.orders/create}}", or json: "@payloads/order.json"
    # body: "raw text"           # instead of json
    # form: { a: 1 }             # instead of json: application/x-www-form-urlencoded
    auth: { type: bearer, token: "{{env.API_TOKEN}}" }
  expect: [ "status == 201", "body.id" ]

Output: status, headers (lower-case names), body (parsed JSON, otherwise text), and auth when the request signs in.

Signing in: request.auth

Keep credentials in {{env.NAME}} (a local or CI variable), never literal.

auth: { type: bearer, token: "{{env.API_TOKEN}}" }
auth: { type: basic, username: ann, password: "{{env.API_PASSWORD}}" }
auth: { type: api-key, name: X-Api-Key, value: "{{env.API_KEY}}", in: header }   # or in: query
auth:                            # OAuth 2 token endpoint (Duende, Entra, Keycloak…)
  type: oauth2
  grant: client-credentials      # or password (add username, password)
  token-url: "{{env.idp}}/connect/token"
  client-id: argus
  client-secret: "{{env.CLIENT_SECRET}}"
  scope: orders.read
  params: { audience: orders }   # optional extra form fields
auth:                            # call a sign-in endpoint first
  type: login
  request: { method: POST, url: "{{env.api}}/auth/login", json: { user: "{{env.API_USER}}", password: "{{env.API_PASSWORD}}" } }
  token: body.access_token       # where the token is in its { status, headers, body }
  # cookie: SESSION              # instead of token: send the session cookie it sets
  header: Authorization          # default; scheme: Bearer (default; "" sends the token alone)
  expires-in: 30m                # optional; else the response's expires_in
auth: { use: login }             # sign in like step `login` did (reuses its token)

oauth2 and login tokens are kept for the rest of the test: a later step with the same auth, or auth: { use: <step id> }, sends the kept token without signing in again, until it expires or the API answers 401 (then it signs in once more and resends). cache: false signs in every time. The auth output says type, from (given, sign-in or kept), via, expires_in and renewed, never the token.

In the desktop

The HTTP step's Config tab is a request builder like the API explorer's: the step's id (its name on the canvas; renaming it updates the steps that read it), a method menu and URL bar with Send, and tabs for Params, Headers, Body, Auth and Vars.

• Send runs just this step and shows the response (Body, Headers, Request, Copy as cURL), even in a test that has never run.
• The Auth tab picks the type with chips. Keep it in the OS keychain turns a secret you typed into a local variable and writes {{env.NAME}} instead. A kept token shows on a line with Forget token.
• The Body tab has a Payload library… list (7.8).
• From API explorer… lists the API explorer's saved requests and copies one in: {{x}} becomes {{env.x}}, and secrets become {{env.<STEP>_<FIELD>}} for you to set as local variables.

6.2 mcp

Calls a tool on an MCP server defined in argus.yaml (mcp:) or an mcpServers file (8.6).

- id: order
  type: mcp
  server: orders
  tool: get_order
  args: { id: "{{steps.create.body.id}}" }
  expect: [ "result.status == 'shipped'" ]

Output: result (the tool's structuredContent, else its text parsed as JSON), text, is_error. A tool answering isError fails the step; a server that can't start or be reached is an infrastructure error. A stdio server is started on first use and shared by every later step in the run; its stderr during the step is kept as evidence (<server>.stderr.log, masked).

6.3 script

Runs a script in the test's folder.

- id: token
  type: script
  lang: python                   # sh (default), bash, python, node, pwsh
  run: |
    import json, os
    print(json.dumps({"token": os.environ["SEED"]}))
  env: { SEED: "{{env.seed}}" }
  # file: tools/make_token.py    # instead of run; args: [..] for both

Output: stdout parsed as JSON when it is an object or list (so {{steps.token.token}}), otherwise stdout, stderr and exit_code. A non-zero exit fails the step. Interpreters: python3 (ARGUS_PYTHON), node (ARGUS_NODE), bash, pwsh, sh. Scripts get at least 10 minutes unless a limit is set for them (step, test, folder, timeouts.script; none for no limit). Files written to $ARGUS_EVIDENCE_DIR become evidence (pytest --output "$ARGUS_EVIDENCE_DIR").

6.4 sql

Queries or changes a database: PostgreSQL, SQL Server, Oracle or SQLite, each through its own native driver (no ODBC, no MCP server).

- id: invoice
  type: sql
  connection: orders-db          # a postgres, sqlserver, oracle or sqlite connection
  query: SELECT id, total FROM invoices WHERE order_id = :id
  params: { id: "{{steps.create.body.id}}" }
  expect: [ "count == 1", "row.total > 0" ]

- id: cleanup
  type: sql
  connection: orders-db
  exec: |
    DELETE FROM invoices WHERE order_id = :id;
    DELETE FROM orders WHERE id = :id;
  params: { id: "{{steps.create.body.id}}" }
  always: true

Oracle names unquoted columns in upper case (row.TOTAL), or alias them (total AS "total"). Oracle needs Instant Client at run time (in the argus:full image; elsewhere ORACLE_CLIENT_LIB or the connection's client_lib_dir). Stop and the step's timeout cancel a running statement on the server (Postgres cancel, Oracle break, SQL Server dropped connection, SQLite interrupt), and the drawer shows progress lines while it waits.

In the desktop

• DATABASE: the connections of SQL types, each with a badge and Test, and buttons to create a PostgreSQL, SQL Server, Oracle or SQLite connection.
• STATEMENT: a Query / Execute switch, starter statements per engine and a SQL editor; Run query or ⌘↵ runs the step alone.
• PARAMETERS: a row per :name, flagging missing and unused ones.
• RESULT: a grid of the rows, with chips that copy a reference ({{steps.invoice.row.total}}) or add a check (count == 1).

6.5 kafka

Produces or consumes Kafka messages. One action per step, on a kafka connection. Argus never joins a consumer group or commits offsets, so reading never takes messages away from the application's consumers.

- id: publish
  type: kafka
  connection: events
  produce:
    topic: orders.created
    key: "{{steps.create.body.id}}"          # partition = hash of the key, as the Java client
    value: { orderId: "{{steps.create.body.id}}", status: NEW }   # or "{{payload.events/order-created}}"
    headers: { type: OrderCreated }
    # partition: 2, timestamp: "2026-10-29T08:00:00Z", compression: gzip|snappy|lz4|zstd
    # format: json|text|base64|avro (+ schema: a registry subject, an id, a .avsc file or the schema)
    # messages: [ { key, value, headers }, ... ]   # several at once
  expect: [ "count == 1" ]

- id: shipped
  type: kafka
  connection: events
  consume:
    topic: orders.shipped
    from: -5m                     # earliest | latest | an offset | 2026-10-29 08:00 (UTC) | RFC 3339 | -15m / 2h ago
    until: "value.orderId == steps.create.body.id"   # stop at the first message that matches
    wait: 30s                     # listen this long; `end` = only what the topic holds now
    max: 10                       # at most this many messages (default 100)
    where: [ "headers.type == 'OrderShipped'", "value.total > 0" ]
    # key: ORD-1, headers: { type: X }, partition: 0, offset: 1234, last: 5, to: 2026-10-29 09:00
    # format / key-format: auto | json | text | avro | base64
  expect: [ "matched.value.status == 'SHIPPED'" ]

Produce output: count, partition, offset, offsets, timestamp, messages. Consume output: messages (each with partition, offset, timestamp, key, value (parsed JSON or decoded Avro), headers, schema_id), count, read (before filters), first, last, matched (the until message), stopped (max, until, end, wait or to), next_offsets, problems.

An until that never matches within wait fails the step as a timeout. To check that nothing arrives: wait: 10s and expect: [ "count == 0" ]. Avro and JSON Schema values are decoded through a Confluent schema registry (schema-registry on the connection); local schemas are registered under <topic>-value.

In the desktop

The Config tab starts with a Consume / Produce switch, Start from recipes (newest 10, last 5 minutes, from a date, wait for a match), topic chips read from the cluster, Try it (runs the step alone) and a preview of the last try.

6.6 redis

Reads and checks what an application cached, and prepares cache data for a test.

- id: cart
  type: redis
  connection: cache
  get: "cart:{{steps.login.body.user_id}}"
  expect: [ found, "ttl > 0", "value.items[0].sku == 'A1'" ]

db: 2 overrides the connection's database. An error reply (WRONGTYPE, NOPERM) fails the step; an unreachable server or refused sign-in is infrastructure.

The composer has a CACHE picker, a Get / Keys / Set / Delete / Command switch with recipes, Run, the RESULT as pretty JSON or a table with "use" and "check" chips, and an OPTIONS section.

6.7 transform

Reshapes earlier steps' data for later ones, without calling anything. The reshaped data shows on the canvas and in the report.

- id: openIds
  type: transform
  input: "{{steps.query.rows}}"
  pipe: [ "where(state, OPEN)", "pluck(id)" ]       # or one text: "where(state, OPEN) | pluck(id)"
  set:
    csv: "{{steps.query.rows | pluck(id) | join(',')}}"
  expect: [ "value.length >= 1" ]

Output: value (the input after pipe) and each set name: {{steps.openIds.value}}, {{steps.openIds.csv}}. The transforms are listed in 7.3.

6.8 ssh

Runs a command on a host through the system's OpenSSH client, so your agent, ~/.ssh/config, jump hosts and keys work as they do in a terminal.

- id: batch
  type: ssh
  connection: batch-host
  command: /opt/batch/run.sh --date {{now}}
  expect: [ "exit_code == 0", "stdout contains 'done'" ]

Output: stdout, stderr, exit_code, and json when stdout is JSON. A non-zero exit fails the step unless an expect checks exit_code. Host-key questions are always answered no; see 8.3 for host keys in CI.

6.9 sftp

Copies files to and from a host.

- id: upload
  type: sftp
  connection: batch-host
  put: { local: data/in.csv, remote: /inbox/in.csv }      # or a list
- id: download
  type: sftp
  connection: batch-host
  get: { remote: /outbox/out.csv }                        # without local: kept as evidence

Output: transferred (direction, local, remote and bytes per file). The report previews downloaded text files.

6.10 kubectl

Runs your own kubectl against an AKS or Kubernetes connection. One action per step:

- { id: pods, type: kubectl, connection: qa2-aks, get: pods, selector: app=orders }
- { id: logs, type: kubectl, connection: qa2-aks, logs: deployment/orders, tail: 200, since: 10m }
- { id: env, type: kubectl, connection: qa2-aks, exec: "printenv FEATURE_X", pod: orders-7d9f }
- { id: rolled, type: kubectl, connection: qa2-aks, rollout: deployment/orders, timeout: 5m }
- { id: any, type: kubectl, connection: qa2-aks, args: [get, configmap, orders, -o, json] }

get returns json, items and count; every action returns stdout, stderr and exit_code. namespace overrides the connection's; container picks one for logs and exec. rollout waits for rollout status within the step's timeout. kubectl (and az / kubelogin when the connection uses them) must be on PATH.

6.11 branch

Runs one list of steps or another.

- id: if-invoiced
  type: branch
  if: "steps.order.body.state == 'INVOICED'"
  then: [ { id: fetch-invoice, type: http, request: { url: "{{env.api}}/invoices/{{steps.order.body.id}}" } } ]
  else: [ { id: no-invoice, type: assert, expect: [ "steps.order.body.total == 0" ] } ]

Output: taken (then or else). The canvas and report draw then and else lanes; the lane not taken shows as not run.

6.12 loop

Runs its steps once per item of a list.

- id: each-sku
  type: loop
  over: "{{steps.catalog.body.skus}}"   # or a literal list
  as: sku                               # default item; also vars.index
  steps:
    - id: stock
      type: http
      request: { url: "{{env.api}}/stock/{{vars.sku}}" }
      expect: [ "status == 200" ]

Output: a list with one object per iteration, keyed by the inner step ids: {{steps.each-sku[0].stock.body}}. The canvas draws a container; the run view and report show one section per iteration and open on the one that failed.

6.13 poll-until

Repeats one step until its output matches.

- id: wait-shipped
  type: poll-until
  until: "body.state == 'SHIPPED'"     # against the inner step's output
  every: 5s                            # default 2s
  max: 2m                              # default 30s
  step: { id: status, type: http, request: { url: "{{env.api}}/orders/{{steps.create.body.id}}" } }

Output: the inner step's last output. For a single step, retry: does the same with less nesting; use poll-until when the polled step should show as its own card.

6.14 sub-flow

Runs a flow file (5.6).

- id: login
  type: sub-flow
  use: flows/login
  with: { user: "{{env.user}}", password: "{{env.password}}" }

Output: the flow's step outputs by id: {{steps.login.token.body.token}}.

6.15 assert

Checks values from earlier steps without calling anything.

- id: totals-match
  type: assert
  expect: [ "steps.invoice.rows[0].total == steps.create.body.total" ]

6.16 manual

A step a person does: the test stops there as pending until a tester records the result.

- id: verify-letter
  type: manual
  action: Open the PDF letter sent to the customer
  expected: The letter shows the new total and the order number

Both action and expected are required. Record the result in the web app's execution player, or resume on the command line (9.9).

6.17 playwright

Runs a Playwright spec (TypeScript/JavaScript, or Python with pytest).

- id: checkout
  type: playwright
  spec: e2e/checkout.spec.ts     # relative to the test file (or to cwd)
  cwd: ../web-app                # optional: where to run npx playwright test
  grep: "(^|\\s)pays with a card(\\s@\\S+)*$"   # optional: one test by title
  project: chromium              # optional; config: playwright.config.ts; args: [..]
  env: { ARGUS_PASSWORD: "{{env.password}}", BASE_URL: "{{env.web}}" }

Each test.step becomes a sub-step in the run view; screenshots, videos and traces become evidence. Output: status, passed, failed, flaky, tests (title, ok, error …) and values: what the spec hands back to later steps as argus:value annotations:

test.info().annotations.push({ type: 'argus:value', description: JSON.stringify({ orderNo }) });

read as {{steps.checkout.values.orderNo}}. The step's timeout is Playwright's test timeout. While it runs, the card shows the current action and elapsed time, and the drawer streams Playwright's output.

Python (pytest-playwright). A spec that is a .py file or pytest node id (or runner: pytest) runs python -m pytest (the nearest .venv / venv, else ARGUS_PYTHON; ARGUS_PYTEST overrides the command), with each test as a sub-step:

- id: login
  type: playwright
  cwd: ../web-tests
  spec: tests/test_login.py::TestLogin::test_ok
  screenshot: only-on-failure    # default; on | off
  video: retain-on-failure       # optional: on | off | retain-on-failure
  trace: retain-on-failure       # optional

grep becomes -k and project becomes --browser. A limit set for the step (its timeout:, the test's, its folder's, or timeouts.pytest / timeouts.playwright) stops the whole pytest run; the run-wide step timeout does not. For a per-test limit use pytest-timeout through args.

Headed runs. argus run --headed, ARGUS_HEADED=1 or the desktop's Show the browser runs specs with --headed; on Windows the browser is brought in front of the app.

6.18 robot

Runs one Robot Framework test.

- id: login-page
  type: robot
  suite: .robot/ui/login.robot   # default .
  test: Login page opens         # required: the Robot test name
  variables: { BASE_URL: "{{env.web}}" }   # --variable NAME:value
  env: { TEST_ENV: qa }          # environment for the suite (%{NAME})

Each keyword becomes a sub-step carrying Robot's whole keyword tree (nested keywords, FOR and WHILE iterations, IF/ELSE, TRY/EXCEPT, setup and teardown, with arguments, messages, status and time); log.html and screenshots are evidence. Output: status, passed, failed, tests.

Argus finds Robot on PATH, in Python's Scripts folders, or as python -m robot for each Python it finds (ARGUS_ROBOT overrides). If it is missing, the step says Robot Framework is not installed and the desktop offers Install Robot Framework. Headed runs pass ${HEADLESS} = False and ${HEADED} = True and (Robot Framework 7+) force Browser library and SeleniumLibrary browsers visible.

6.19 load and page-perf

load runs many virtual users through nested steps and measures latency, throughput and errors; page-perf measures how fast a page loads in a real browser. Both are described in chapter 12.

- id: orders-load
  type: load
  users: 50
  ramp-up: 30s
  duration: 2m
  steps:
    - { id: list, type: http, request: { url: "{{env.api}}/orders" }, expect: [ "status == 200" ] }
  expect: [ "latency.p95 < 500", "error_pct < 1" ]

- id: home-speed
  type: page-perf
  url: "{{env.web}}/dashboard"
  runs: 5
  expect: [ "lcp.p75 < 2500" ]

6.20 email

Sends a message through an smtp, sendgrid or ses connection, filled from earlier steps, with attachments.

- id: notify
  type: email
  connection: mail
  to: "{{steps.owners.rows | pluck(email)}}"   # text (commas), a list, or rows with `email`
  cc: qa-leads@example.com                     # also bcc, reply-to; from: wins over the connection's
  subject: "{{steps.query.count}} open orders"
  body: |                                      # text; html: for an HTML version
    Open: {{steps.query.rows | pluck(id) | join(', ')}}
  attach:
    - results                    # this test so far: report.html, output.json, evidence (results.zip)
    - report                     # report.html alone
    - exports/daily              # a file, or a folder (zipped as daily.zip)
    - { evidence: ui }           # an earlier step's evidence files
    - { name: open.csv, content: "{{steps.query.rows | format('{id},{total}') | join('\n')}}" }
    - { file: [ a.csv, b.csv ], zip: exports }
  zip: nightly                   # optional: every attachment in one nightly.zip
  # send: false                  # build the message and zip as evidence, don't send
  # max-size: 30MB               # attachments allowed in total (default 18MB)
  expect: [ "sent == true" ]

Without body or html the body is a summary of the test's steps so far. Argus's own files are masked before they are attached. Output: sent, provider, message_id, from, to, cc, bcc, subject, attachments, bytes, and zip (the path of the zip it made), so the next step can use it: { type: sftp, put: { local: "{{steps.notify.zip}}", remote: /inbox/r.zip } }.

ARGUS_EMAIL_REDIRECT=me@example.com sends every message to that one address instead (subject [test] …, the real recipients named at the top), which is what you want on a shared QA environment.

In the desktop

The Config tab shows the message as it would go out with the last run's data, lets you add and remove attachments (results, report, files, an earlier step's evidence), Zip all, and Send test, which sends it to you only (your address is remembered).

6.21 desktop-app

Drives a native desktop app (a Windows program, a macOS app, a Linux GTK/Qt app) on the machine that runs the test, through its accessibility tree: UI Automation on Windows, the Accessibility API on macOS, AT-SPI and XTest on Linux (X11). Elements are found by what they show, not by screen position, and every action waits for its element.

- id: add-invoice
  type: desktop-app
  app: Billing                # its name as the system shows it (or a window title, or a pid)
  launch: '"C:\Program Files\Billing\billing.exe" --env qa'   # started when not running
  close: true                 # default: close it when this step started it
  wait: 10s                   # how long each action waits for its element
  screenshots: end            # end (default: last action and a failure) | each | failure | none
  actions:
    - click: { name: "New invoice", role: button }
    - type: { into: { name: Customer }, text: "{{env.customer}}" }
    - set: { name: Amount, to: "42.50" }   # sets a field's value directly
    - press: ctrl+s
    - expect: { name: Status, value: Saved }
    - expect: { name: "Unsaved changes", gone: true, timeout: 3s }
    - read: { name: "Invoice number", as: invoice }
    - check: { id: sendCopy }               # ticks it only if it is not ticked
    - expand: Advanced
    - click: Export…
    - window: Export                       # act in the Export dialog from here on
    - click: Cancel                        # back in the main window once the dialog closes
    - click: Copy number
    - expect: { clipboard: "{{steps.add-invoice.values.invoice}}" }
    - screenshot: saved

Finding elements. A plain string matches an element's name, description or id. A mapping narrows it: name (or text), role (or class), id, desc, value, contains (part of the name or value, any case), index (the nth match, from 0), or x/y relative to the window. A state narrows it further: checked, expanded, selected, enabled or focused (true or false); an element without that state never matches.

id is the id the app's developers gave the element for testing: the AutomationId on Windows, the accessibility identifier on macOS, the accessible id on Linux. It stays the same when a label is reworded or translated, so tests the assistant saves use it whenever the element has one. Ask the app's developers to set it on the controls your tests use.

Actions. click, double_click, right_click, type (text into the focused field, or { text, into }), press (Enter, ctrl+shift+p), set (to), scroll (down, or { dy, dx } over an element), drag (from, to), wait (an element, or a duration), expect (an element, with value or gone), read (as: keeps its value, else its name), screenshot (a name), sleep, and action (do: an accessibility action such as expand or toggle). Any action takes timeout and optional: true.

• check and uncheck set a check box, radio button or switch and confirm it took; they click only when it is not already that way, so a rerun never flips it back. expand and collapse do the same for tree items, combo boxes and expandable sections, through accessibility first so the pointer does not move.
• select chooses a list or table row, a tab, a radio button or a combo option through accessibility (a click when it cannot), and does nothing when it is already selected. scroll_to scrolls an element into view without the mouse wheel.
• window waits for a window of the app whose title holds the text (a dialog such as Save As) and acts in it from then on. When that window closes, the actions go back to the app's front window by themselves. window: { title: Export, gone: true } waits for it to close. expect: { window: Export } (with gone: true too) only checks.
• clipboard: text puts text on the clipboard; expect: { clipboard: text } checks what a Copy put there; read: { clipboard: true, as: name } keeps it. Desktop apps only.
• resize: 1280x800 (or { width, height, x, y }), move: 0,0 (or { x, y }), maximize, minimize, restore and focus change the app's window and confirm it took. When the app or the screen will not allow the size, the step says what it got instead.

Ready to act. Before a click, a type into a field, a set or a check, the action waits (up to its timeout) for the element to be enabled, so a button that the app turns on a moment later is clicked once it can be. A disabled element fails with "… is disabled" rather than a click that did nothing. set reads the field back and fails when the app kept another value (a number field that rounds, a mask that drops characters); verify: false skips that check.

launch runs in the test's folder, so a path like ../shop.py works.

Output: values (what read kept, so {{steps.add-invoice.values.invoice}}), passed, actions (each with ms, ok, error, screenshot), screenshots, app, pid. Screenshots are the step's evidence.

Electron and Chromium apps. Many desktop apps are a web page in a window (Teams, Slack, VS Code and most in-house Electron tools). Their accessibility tree is thin and slow, but started with a debugging port they can be driven like a web page with Playwright. cdp: true (or a port number) adds the port switch to launch and keeps the app open after the step; the output's cdp is the address a playwright step connects to:

- id: app
  type: desktop-app
  app: Billing
  launch: '"C:\Program Files\Billing\Billing.exe"'
  cdp: true                    # needs launch: the app must start fresh
  actions: []
- id: invoice
  type: playwright
  spec: billing.spec.ts        # import { appTest as test } from './argus-playwright'
  cdp: "{{steps.app.cdp}}"
- id: close-app
  type: desktop-app
  app: Billing
  close: true
  actions: []

In the spec, appTest's page is the app's window; Playwright disconnects at the end and leaves the app running. Native parts (menus, file dialogs, other windows) stay with desktop-app steps. If the app is already running the step stops and says to close it first, since only a fresh start opens the port. The assistant writes all three steps when it drove the app with computer_launch_app and cdp: true.

The easiest way to write one is to let the assistant drive the app and save what it did (13.5). The step palette has DESKTOP APP under UI; the card's badge is APP.

6.22 mobile-app

Drives an app on an Android emulator or device (through adb) or an iOS simulator (on a Mac, through xcrun simctl and idb), with the same actions as desktop-app plus tap, long_press, swipe (up/down/left/right, { from, to }, or { until: <element>, direction, max }), back, home, launch, stop and open (a URL or deep link).

- id: sign-in
  type: mobile-app
  platform: android           # android | ios
  app: com.example.shop       # package, package/.Activity, or iOS bundle id; started fresh
  device: emulator-5554       # optional: default the only one running
  install: build/shop.apk     # optional: installed first (relative to the test)
  reset: true                 # optional: clear the app's data first
  actions:
    - type: { into: { id: email }, text: "{{env.user}}" }
    - type: { into: { id: password }, text: "{{env.password}}" }
    - tap: Sign in
    - expect: { contains: Welcome }
    - swipe: { until: { text: Orders }, direction: up }
    - tap: Orders
    - read: { id: order_count, as: orders }
    - screenshot: orders
  expect: [ "values.orders != '0'" ]

id matches an Android resource id with or without its package (email matches com.example.shop:id/email). Points are Android pixels or iOS points. restart: false keeps the app where it is, launch: false leaves it unstarted, close: true stops it afterwards.

Output: values, passed, actions, screenshots, device, platform, app.

What it needs. The emulator or simulator must be running on the machine that runs the test (start one in Android Studio's Device Manager, or with emulator -avd <name>). Argus finds adb through ARGUS_ADB, then ANDROID_HOME / ANDROID_SDK_ROOT, then the SDK's default folder (%LOCALAPPDATA%\Android\Sdk on Windows), then PATH. For iOS install idb (brew install idb-companion and pip install fb-idb); ARGUS_IDB points at it if it isn't on PATH. Android typing is ASCII only.

The step palette has MOBILE APP under UI; the card's badge is MOB.

Steps hand data to each other through {{...}} expressions. This chapter covers what an expression can read, how to reshape a value on the way, how assertions work, how to run a step or a test once per row of data, and the project's payload library. It ends with the desktop tools that write expressions for you.

Watch the video: Desktop 3: Passing data between steps 1:21

7.1 Expressions

{{...}} can appear in any string field of a step.

• Paths use dots and [n]; .length is the size of a list, string or object.
• Arithmetic and comparisons work inside: {{steps.count.rows[0].n + 1}}.
• A value that is exactly one expression keeps its JSON type: json: { ids: "{{steps.q.rows}}" } sends a list, not text. Otherwise values are spliced in as text ("Order {{steps.create.body.id}} created").
• A reference to an unknown step or a later step is a validation error.

7.2 Where data comes from, on screen

With Data lines on, the canvas connects each step to the steps it reads from. The inspector's Data tab lists them in Where this step's values come from, and every field shows a lens under it (7.7).

7.3 Transforms

Add transforms after a | to fit one step's result to what the next needs. They apply left to right:

url: "{{env.api}}/orders?ids={{steps.query.rows | where(state, OPEN) | pluck(id) | join(',')}}"
json: { lines: "{{steps.order.body.lines | pick(sku, qty)}}" }
body: "{{steps.user.body | format('{first} {last}')}}"

Arguments are bare words (field names), quoted text or numbers; quote text that holds a comma, bracket or space (join(', ')). A missing value is null to transforms, so | default(0) fills it.

Unknown transforms and missing arguments are validation errors.

A transform step (6.7) does the same as a step of its own, so the reshaped value shows on the canvas and in the report: { id: openIds, type: transform, input: "{{steps.query.rows}}", pipe: [ "where(state, OPEN)", "pluck(id)" ] } gives {{steps.openIds.value}}.

7.4 Assertions

expect (and retry.until, branch.if, poll-until.until, a consume's until and where) take assertion expressions:

expect:
  - "status == 201"
  - "body.items.length >= 1"
  - "body.type == 'UNKNOWN'"
  - "body.id"                                         # a bare path must be truthy
  - "status == 200 && (body.state == 'OPEN' || body.retries < 3)"
  - "body.ids contains 42"
  - "body.ref matches '^ORD-[0-9]+$'"
  - "steps.invoice.row.total == body.total"

• Bare paths read the step's own output; steps.<id>.<path> reads earlier steps (in an assert step that is all there is).
• Operators: == != > >= < <=, contains (substring, list item, object key), matches '<regex>', && / and, || / or, ! / not, parentheses, + - * / %.
• Strings in single or double quotes.
• A number equals the same number written as text, and true / false equal the words, so CSV cells compare naturally (status == data.expected).
• Each assertion records the actual value it compared (for && / ||, each comparison's left side). The run view's Assertions tab and the report show expected against actual.

7.5 Retries

retry: { until: "status == 200", every: 2s, max: 30s }   # poll until the condition holds
retry: { times: 3, every: 5s }                            # run again while the step fails (its expect included)

7.6 Data sets

On a test: the whole test per row

id: TC-1042
title: Orders in every currency
data: data/orders.csv          # CSV with a header row, a JSON list of objects, or a YAML list of mappings
steps:
  - id: create
    type: http
    request: { method: POST, url: "{{env.api}}/orders", json: { currency: "{{row.currency}}", qty: "{{row.qty}}" } }

The test runs once per row as TC-1042[1], TC-1042[2] …, reading {{row.<column>}}. The file is looked up from the argus.yaml folder, then beside the test. argus-server maps every row's result to test case TC-1042.

On a step: one step per row

- id: signIn
  type: http
  data: data/users.csv                 # or { file: … }, or rows in place:
  # data: [ { user: ann, expected: 200 }, { user: bob, expected: 403 } ]
  request: { method: POST, url: "{{env.api}}/login", json: { user: "{{data.user}}" } }
  expect: [ "status == data.expected" ]

• The step runs once per row as signIn[0], signIn[1] …, with the row's values as {{data.<column>}} (in expect as data.<column>).
• Every row runs, even after one fails; the step fails if any row did.
• Later steps read the rows' outputs as {{steps.signIn[1].body}}, and steps.signIn.length is the row count.

In the desktop

The step's Data tab starts with a DATA SET section: the rows with a status dot per row after a run, column chips that insert {{data.<column>}}, New data file (creates data/<test>-<step>.csv with the columns the step reads), Use another file, Open in editor and Remove. Run step uses picks which row a single-step run uses.

In Files, data files open in a Table view to edit cells directly (4.8).

7.7 Insert value and the reference lens

You rarely need to type a {{...}} by hand.

{x} Insert value sits beside every field that takes a value (and the HTTP URL bar). It opens a picker of everything the step can read: earlier steps' outputs (with their last-run values), environment variables, data columns, payloads, vars. Pick one and the reference is inserted at the cursor.

The lens under each field shows, for every {{...}} in it, where it comes from (a step, env, data, a payload) and what it resolved to on the last run. Broken references are red: an unknown step, a later step, a missing field, an undefined variable. Click a reference to edit it: change the source, add transforms, and see the result update as you go, then Update in .

Change a value includes a field mapper: for a list of objects, tick the fields to keep and type new names to rename them; Argus writes the matching pick(...) and rename(...) transforms.

The Data tab's "Use a value" card

The Data tab lists every earlier step's result as a tree. Click a value to open Use a value: it shows what the value gives on the last run while you add transforms (suggested for the value's shape, such as pluck(id) for a list of rows, or typed), then either inserts it into the field you were editing or saves it as a transform step before the selected step and puts {{steps.<id>.value}} in the field.

7.8 The payload library

Request bodies, messages and documents the project reuses live in one folder, payloads/ beside argus.yaml (sub-folders are fine). A payload's name is its path there without the extension: payloads/orders/create.json is orders/create. When two files share a name, add the extension (orders/create.xml).

Use it in any field:

- id: create
  type: http
  vars: { qty: 3 }                         # the payload reads {{vars.qty}}
  request: { method: POST, url: "{{env.api}}/orders", json: "{{payload.orders/create}}" }
- id: getOrder
  type: http
  request: { method: POST, url: "{{env.api}}/soap", headers: { Content-Type: text/xml }, body: "{{payload.soap/get-order}}" }
- id: publish
  type: kafka
  connection: events
  produce: { topic: orders.created, value: "{{payload.events/order-created | omit(internal)}}" }

// payloads/orders/create.json
{ "sku": "A1", "qty": {{vars.qty}}, "customer": "{{env.customer_id}}" }

• JSON and YAML payloads read as values (so json:, Kafka and Redis values keep their shape, and transforms work on them); CSV reads as a list of rows (usable as data: "{{payload.users}}"); XML and other text reads as text; binary files as base64.
• {{...}} inside a payload resolves where it is used: the step's vars:, env, earlier steps, data rows, other payloads. In JSON a bare "qty": {{vars.qty}} is allowed and keeps the value's type.
• A payload the library doesn't have stops the run before it starts, naming the closest names.
• The older json: "@file.json" (a file beside the test) still works and also finds library payloads by name.
• In CI the library is found from argus.yaml's folder, else the nearest payloads/ above the test, the working folder or $CI_PROJECT_DIR.

The Payloads screen

The Payloads screen (⌘8, the package in the rail) manages the library:

• Upload files (button, or drop them on the screen), or New to write a JSON / YAML / XML / text / CSV payload.
• Edit in place and save (⌘S); Format JSON.
• Update from file replaces one with a newer file.
• Rename / move: tests and payloads that read it are rewritten.
• Remove, and Used by: which tests read it.
• Insert into the step: put {{payload.<name>}} in the field being edited.

The HTTP composer's Body tab has a Payload library… list (XML adds the Content-Type), the Data tab shows the library as chips, and payloads are a group in every field's value picker.

From the command line and the assistant:

argus payloads list
argus payloads show orders/create
argus payloads add ./order.json --name orders/create
argus payloads rename orders/create orders/create-basic   # references follow
argus payloads remove orders/old

The MCP tools are list_payloads, read_payload and save_payload.

A step that talks to a system names a connection; the connection's settings live in argus.yaml, and its secrets come from the OS keychain, local variables or CI/CD variables. This keeps tests portable: the same test runs against qa2 or uat by picking an environment.

connections:                       # shared by every environment
  batch-host: { type: ssh, host: batch01.qa, user: qa, key: "${BATCH_SSH_KEY}" }
environments:
  qa2:
    connections:                   # only qa2; wins over a shared one of the same name
      orders-db: { type: postgres, url: "${QA2_PG_URL}" }

Watch the video: Desktop 4: Connections and variables 1:20

8.1 Connection types

Examples:

connections:
  orders-db:
    type: sqlserver
    host: sql01.qa
    database: orders
    user: qa
    password: "${keychain:shared.orders-db.password}"
    encrypt: required
    via: bastion                  # tunnel through an ssh connection
  ledger:
    type: oracle
    host: ora01.qa
    service: LEDGER
    user: qa
    password: "${LEDGER_PW}"
  cache:                          # Azure Cache for Redis
    type: redis
    host: orders.redis.cache.windows.net
    port: 6380
    tls: true
    password: "${REDIS_ACCESS_KEY}"
  events:                         # Confluent Cloud
    type: kafka
    brokers: pkc-xxxx.westeurope.azure.confluent.cloud:9092
    security: sasl_ssl
    user: "${KAFKA_API_KEY}"
    password: "${KAFKA_API_SECRET}"
    schema-registry: https://psrc-xxxx.westeurope.azure.confluent.cloud
  eventhubs:                      # Azure Event Hubs (Kafka endpoint)
    type: kafka
    brokers: orders-ns.servicebus.windows.net:9093
    security: sasl_ssl
    user: $ConnectionString
    password: "${EVENTHUBS_CONNECTION_STRING}"
  mail:
    type: smtp
    host: smtp.office365.com
    port: 587
    user: qa@example.com
    password: "${keychain:shared.mail.password}"
    from: Argus QA <qa@example.com>