Your first automation

This page runs the example automation that ships in the repository, process-orders, from start to finish. It assumes the demo application is already up, so read Install first if it is not. When the run finishes you will have a folder of real evidence on disk and an understanding of what the framework did.

#Run the example

With npm run demo running in one terminal, open a second and run:

npm run automation:run

That script is tsx robot/cli.ts run process-orders. It launches real Playwright headless, drives the demo app and finishes in roughly ten seconds. The Robot accepts a few flags when you call it directly:

npx tsx robot/cli.ts run process-orders --headed      # watch the browser
npx tsx robot/cli.ts run process-orders --no-trace    # skip the Playwright trace
npx tsx robot/cli.ts run process-orders --url http://127.0.0.1:4100

To run any other automation in automations/, use its id: npm run robot:run -- process-invoices. The list verb shows what this checkout can run.

#What the run does

The framework runs a fixed lifecycle, the same shape as a UiPath REFramework process but held in TypeScript.

INIT resets the demo data so the queue is predictable, then signs in through the UI. The automation calls ctx.credentials.get('demoApp'); the username and password never appear in the file.

GET TRANSACTION polls the queue at /api/orders/pending and returns the first order, or null when the queue is empty.

PROCESS runs four small named functions: openOrder, updateOrder, submitOrder, verifySubmitted. Keeping the steps as named calls is deliberate: the Studio derives the workflow diagram from their order, so the picture and the code cannot drift apart.

The exception branches are the point. Six orders are seeded and each ends a different way:

• ORD-1001, ORD-1002, ORD-1003 submit cleanly.
• ORD-BIZ1 is rejected with HTTP 400 and the message "PO number is required". That raises a BusinessException, which is expected and never retried, so a screenshot is taken.
• ORD-5001 returns HTTP 500 on the first submit. That raises a SystemException, the framework retries and attempt two succeeds. The retry policy is three attempts in total with backoff.
• ORD-5002 returns HTTP 500 every time, so it is retried to exhaustion and ends as a failed transaction.

The result is three successes, one business failure, one recovered by retry and one terminal system failure. Nothing about the path is decided at execution time. If a target cannot be found the run stops and names the element it wanted.

#Where the run artifacts land

Every run gets its own directory under artifacts/<automationId>/<runId>/:

artifacts/process-orders/process-orders-20261001-151221-hi2a/
  logs.jsonl          one JSON object per line, the structured log stream
  logs.txt            the same stream, human-readable
  state.json          machine-readable status the Studio polls while running
  summary.json        the final report: per-transaction outcomes and totals
  trace.zip           the full Playwright trace for the run
  screenshots/        automatic captures taken on business and system failures
  run-diagnostics.json  extra diagnostics, written on some runs

The root is config.artifactsRoot, which resolves to artifacts/ in the repository. Override it per run with --artifacts <dir> if you want evidence somewhere else.

Open the trace with the Studio, or straight from the terminal:

npx playwright show-trace artifacts/process-orders/<runId>/trace.zip

#Read a finished run from the terminal

You do not have to open files by hand. robot show prints the recorded state of a run:

npm run robot -- show process-orders <runId>

The exit code tells a scheduler what happened: 0 means the run finished, including a run that completed with per-transaction errors, because the Robot did its job. 2 is a fatal failure, 3 means an operator stopped it and 1 is a usage or configuration error.

#Things that catch people out

• If the demo application is not running, GET TRANSACTION raises a SystemException with the code QUEUE_HTTP_ERROR. Start the app first.
• A run that ends completed-with-errors still exits 0. Read summary.json for the per-transaction truth rather than trusting a green exit code.
• artifacts/ is gitignored. Runs are local evidence and they are not committed.
• The queue lives in the demo application's memory, so restarting the app brings the six seeded orders back.