@cloudbeat/atlas-cli 0.3.0 → 0.4.0

package/dist/docs/files.md

@@ -0,0 +1,86 @@
+# Test Files
+
+A project holds your test plan and every data file it reads. Upload them
+whenever they change — this is independent of running a test, and files stay in
+the project until you replace or delete them.
+
+## Uploading
+
+From the **Files** tab, upload the `.jmx` and its data files. From the CLI:
+
+```bash
+atlas files upload -p SHOP ./checkout.jmx ./data/users.csv ./data/products.csv
+```
+
+Uploading a file whose name already exists **replaces** it.
+
+## How files are laid out
+
+**All of a project's files live together in one flat folder.** There are no
+subdirectories: whatever you upload lands side by side, and when a test runs,
+the test plan and its data files sit in the same directory on every load
+generator.
+
+So reference data files from your plan by a plain relative path:
+
+```
+./users.csv          ✅  recommended
+users.csv            ✅  also works
+```
+
+Not by an absolute path, and not through a folder:
+
+```
+C:\Users\me\Data\users.csv      ❌  a Windows path cannot be found on a Linux generator
+/home/me/data/users.csv         ❌  absolute paths won't exist there either
+./data/users.csv                ❌  the folder structure is not preserved
+```
+
+If a data file path can't be resolved, every thread in that thread group throws
+before issuing a single request. There are no failed samples, so the summary
+shows `0.00%` errors and the dashboard simply **omits that thread group** while
+the others look healthy.
+
+If a thread group is missing from your results, this is the first thing to check.
+
+## How data files are divided
+
+When a test runs on several machines, Atlas **divides** your data files between
+them rather than giving every machine the whole file. With 1,000 rows across 5
+generators, each gets roughly 200 rows, and no two machines use the same row.
+
+This is what you usually want: a load test where 5 machines all replay the same
+200 users isn't testing what you think it is.
+
+**Header rows are handled for you.** If your plan's CSV Data Set Config says the
+file has a header, that header is copied to every machine's slice and only the
+data rows are divided.
+
+Files are divided byte for byte — column order, quoting, embedded commas and
+newlines all survive exactly as uploaded.
+
+To switch dividing off and send whole files to every machine, use `--no-split`
+(CLI) or clear the split option on the Run Test tab.
+
+`.csv` and `.txt` files are divided. `.jmx` and everything else is copied whole
+to every machine.
+
+## Downloading and deleting
+
+```bash
+atlas files list -p SHOP
+atlas files download -p SHOP checkout.jmx
+atlas files rm -p SHOP old-data.csv
+```
+
+In the web interface, the Files tab has a download and a delete action per file.
+
+## Before your first run
+
+- Every file the plan references must actually be uploaded. Upload the plan and
+  its data files together.
+- Disable GUI listeners left switched on in the plan — **View Results Tree**,
+  **Aggregate Report**, **Simple Data Writer**. They eat memory during a headless
+  run, and Atlas collects results separately.
+
+Full details in [Test Plan Requirements](/reference/test-plans).

package/dist/docs/generators.md

@@ -0,0 +1,52 @@
+# Load Generators
+
+A **load generator** is a machine that runs JMeter and produces load. Atlas
+copies your test plan to each one and starts them together.
+
+Most teams share a pool that is already set up — in that case you can skip this
+section entirely and just pick machines when you [run a test](/guide/running-tests).
+
+Read on if you need to add machines of your own.
+
+## Two kinds
+
+| | |
+|---|---|
+| **Servers** | Fixed machines that exist whether or not a test is running. Cloud VMs Atlas can power on and off, or your own hardware. |
+| **Clusters** | Elastic capacity. Units are created when a test starts and destroyed when it ends. |
+
+Both appear under **Fleet** in the sidebar, on separate tabs.
+
+## Why run your own?
+
+The usual reason is that your application isn't reachable from the internet.
+A load generator inside your own network can reach it, and only needs an
+**outbound** connection to Atlas — no inbound access, no firewall changes, no
+VPN.
+
+The other reason is geography: generating load from where your users actually
+are gives you a more honest number.
+
+## Power state
+
+Machines Atlas can control are **powered on when a test needs them and switched
+off when it ends**, so you don't pay for idle capacity. This is why a switched-off
+machine can still be selected on the Run Test tab.
+
+Machines Atlas can't power — your own hardware — are assumed to be always on and
+are never powered off.
+
+## Status
+
+The Fleet page shows two independent things per machine:
+
+- whether the **machine** is on or off
+- whether its **connection** to Atlas is live
+
+A machine can be on but not connected, which usually means the agent isn't
+running. See [Troubleshooting](/reference/troubleshooting).
+
+## Next
+
+- [Adding a Machine](/generators/adding)
+- [Clusters](/generators/clusters)

package/dist/docs/getting-started.md

@@ -0,0 +1,85 @@
+# Getting Started
+
+This walks through one complete test: uploading a plan, running it, and reading
+the result. It should take a few minutes.
+
+## Sign in
+
+Open your Atlas instance and go to **/app** — for a typical installation that
+is [atlas.cloudbeat.io/app](https://atlas.cloudbeat.io/app). Sign in with
+your email address and password.
+
+If you have access to more than one account, you'll be asked which to work in.
+You can switch later from the account selector in the sidebar.
+
+## Open a project
+
+A **project** holds your test plan, its data files, and the history of every run.
+Pick one from **Projects** in the sidebar, or ask your administrator to create
+one if the list is empty.
+
+The project page has three tabs:
+
+| Tab | What it holds |
+|---|---|
+| **Results** | Every run of this project, newest first |
+| **Files** | The test plan and data files |
+| **Run Test** | Start a new run |
+
+## Upload your test plan
+
+Go to **Files** and upload your `.jmx` along with every data file it reads.
+
+Test plans written in JMeter on Windows usually reference data files by a full
+`C:\...\data.csv` path, which does not exist on a load generator. Open each
+**CSV Data Set Config** and reduce the filename to `./data.csv`.
+
+If a path can't be found at run time, every thread in that thread group stops
+before sending a single request — the test appears to run, but that group
+reports nothing at all. See [Test Plan Requirements](/reference/test-plans).
+
+## Run it
+
+Go to **Run Test**, choose where to run:
+
+- **Servers** — pick individual load generators. Machines that are switched off
+  can still be selected; they are powered on for you.
+- **Cluster** — run on a cluster and say how many units you want.
+
+If the project holds more than one `.jmx`, pick which one to run. Then press
+**Run**.
+
+You do not need to deploy or prepare anything first. Atlas reserves the
+machines, copies your files, and starts JMeter.
+
+## Watch it run
+
+The page switches to a live view showing each stage — powering on, deploying,
+then running — with a **Stop** button.
+
+Once results start arriving, open the dashboard for the run from the **Results**
+tab. You'll see:
+
+- **Active users**, **response time** and **error rate** on one chart
+- Headline numbers: duration, peak users, requests per second, average response
+  time, error rate
+- A per-request table you can sort and drill into
+
+The dashboard updates itself while the test runs. See
+[Reading Results](/guide/results) for what each number means.
+
+## Stop it, or let it finish
+
+A test ends on its own when the plan says so — a thread group's duration or loop
+count running out. Press **Stop** to end it early.
+
+When a run finishes, the load generators are released and any that Atlas powered
+on are switched off again.
+
+## Next steps
+
+- [Running a Test](/guide/running-tests) — all the options, and how data files
+  are divided between machines
+- [Reading Results](/guide/results) — the dashboard in detail
+- [CLI](/cli/install) — do all of this from a terminal or a CI pipeline
+- [Recorder](/recorder/) — generate a test plan by clicking through your app

package/dist/docs/index.json

@@ -0,0 +1,110 @@
+[
+  {
+    "topic": "getting-started",
+    "title": "Getting Started",
+    "summary": "This walks through one complete test: uploading a plan, running it, and reading the result. It should take a few minutes.",
+    "source": "guide/getting-started.md"
+  },
+  {
+    "topic": "projects",
+    "title": "Projects",
+    "summary": "A project is the unit everything else hangs off. It holds:",
+    "source": "guide/projects.md"
+  },
+  {
+    "topic": "files",
+    "title": "Test Files",
+    "summary": "A project holds your test plan and every data file it reads. Upload them whenever they change — this is independent of running a test, and files stay in the project until you replace or delete them.",
+    "source": "guide/test-files.md"
+  },
+  {
+    "topic": "running",
+    "title": "Running a Test",
+    "summary": "Open a project, go to **Run Test**, choose where to run, and press **Run**.",
+    "source": "guide/running-tests.md"
+  },
+  {
+    "topic": "results",
+    "title": "Reading Results",
+    "summary": "Every run has a dashboard. Open it from a project's **Results** tab, or from the test list at `/<project>`.",
+    "source": "guide/results.md"
+  },
+  {
+    "topic": "ai-agents",
+    "title": "Atlas for AI Agents",
+    "summary": "**Describe the test. Let the agent build it.**",
+    "source": "agents/index.md"
+  },
+  {
+    "topic": "agent-setup",
+    "title": "Setting It Up",
+    "summary": "Two commands to install, one to sign in. The guidance is bundled with the CLI, so there is nothing to download separately and nothing to keep in sync by hand.",
+    "source": "agents/setup.md"
+  },
+  {
+    "topic": "agent-tasks",
+    "title": "What an Agent Can Do",
+    "summary": "The whole lifecycle, from an empty project to a report you can send someone. Each section below is a real thing to ask for, what the agent does about it, and what it should ask you along the way.",
+    "source": "agents/capabilities.md"
+  },
+  {
+    "topic": "skills",
+    "title": "The Skills",
+    "summary": "`atlas skills install` writes six skills plus a vendor-neutral `AGENTS.md`. Each skill is a short document covering one part of load testing: what to do, in what order, and which mistakes to avoid.",
+    "source": "agents/skills.md"
+  },
+  {
+    "topic": "automation",
+    "title": "Building Your Own Integration",
+    "summary": "The same surfaces the bundled skills use are there for your own scripts, bots and agents. No SDK, no separate API client: the CLI is the integration point, and everything it does is scriptable.",
+    "source": "agents/automation.md"
+  },
+  {
+    "topic": "generators",
+    "title": "Load Generators",
+    "summary": "A **load generator** is a machine that runs JMeter and produces load. Atlas copies your test plan to each one and starts them together.",
+    "source": "generators/index.md"
+  },
+  {
+    "topic": "clusters",
+    "title": "Clusters",
+    "summary": "A **cluster** is elastic capacity: instead of fixed machines that sit there between tests, units are created when a test starts and destroyed when it ends.",
+    "source": "generators/clusters.md"
+  },
+  {
+    "topic": "recorder",
+    "title": "Recording a Scenario",
+    "summary": "If you don't have a JMeter test plan yet, the recorder makes one by watching you use your application. You click through a flow in a real browser — log in, search, check out — and it writes a `.jmx` you can run as a load test.",
+    "source": "recorder/index.md"
+  },
+  {
+    "topic": "commands",
+    "title": "Commands",
+    "summary": "Every command takes `--json`, and `-p, --project <name>` where a project applies. Run `atlas <command> --help` for the full list of options. A failure under `--json` prints the error as JSON on standard error.",
+    "source": "cli/commands.md"
+  },
+  {
+    "topic": "auth",
+    "title": "Signing In",
+    "summary": "You'll be prompted for your password. The session lasts **8 hours**.",
+    "source": "cli/authentication.md"
+  },
+  {
+    "topic": "ci",
+    "title": "Running in CI",
+    "summary": "The point of running Atlas from CI is to catch a performance regression the same way you catch a failing unit test — automatically, on the build that caused it.",
+    "source": "cli/ci.md"
+  },
+  {
+    "topic": "test-plans",
+    "title": "Test Plan Requirements",
+    "summary": "Atlas runs standard JMeter test plans, but a plan written on a desktop needs a few changes before it runs correctly on a fleet of Linux load generators. These are the things that actually catch people out.",
+    "source": "reference/test-plans.md"
+  },
+  {
+    "topic": "troubleshooting",
+    "title": "Troubleshooting",
+    "summary": "The usual cause is a **data file path that can't be resolved**. Every thread in that group fails before sending a request, so there are no errors to report — the group simply isn't there.",
+    "source": "reference/troubleshooting.md"
+  }
+]

package/dist/docs/projects.md

@@ -0,0 +1,50 @@
+# Projects
+
+A project is the unit everything else hangs off. It holds:
+
+- one or more **test plans** (`.jmx`)
+- the **data files** those plans read
+- the **history** of every run, with its results
+
+Projects are also how access is granted: you see the projects you have been
+given access to, and nothing else.
+
+## The project page
+
+### Results
+
+Every run of this project, newest first. Each row shows when it started, how
+long it ran, and the peak number of concurrent users it reached. Click a run to
+open its dashboard.
+
+You can give a run a **name** — click the name cell and type. This is worth
+doing when you run variations against each other, since `SHOP-20260818-194201`
+tells you when a run happened but not what it was for. "Baseline, 500 users" is
+easier to find three weeks later.
+
+### Files
+
+Upload, download and delete the project's files. See
+[Test Files](/guide/test-files).
+
+### Run Test
+
+Start a run. See [Running a Test](/guide/running-tests).
+
+## Choosing which plan runs
+
+A project can hold several test plans. One of them is the project's **default** —
+the one used when you don't say otherwise.
+
+When a project holds more than one `.jmx`, the Run Test tab shows a dropdown to
+pick between them, and remembers your last choice for that project. From the
+CLI, pass `--jmx`:
+
+```bash
+atlas run -p SHOP --jmx checkout-peak.jmx --servers 5
+```
+
+## Creating a project
+
+Projects are created by administrators. If you need one, ask — you'll need to
+say which account it belongs to, since that determines who can see it.

package/dist/docs/recorder.md

@@ -0,0 +1,143 @@
+# Recording a Scenario
+
+If you don't have a JMeter test plan yet, the recorder makes one by watching you
+use your application. You click through a flow in a real browser — log in,
+search, check out — and it writes a `.jmx` you can run as a load test.
+
+## Install
+
+```sh
+npm install -g @cloudbeat/atlas-recorder
+```
+
+This downloads a private browser build (a few hundred MB) used for capture. It
+won't touch the browsers you already have. Requires Node.js 18 or newer.
+
+It's a separate package from the CLI because CI machines run tests but never
+record them.
+
+## Record
+
+```sh
+atlas-rec record https://example.com -o checkout.jmx -n "Checkout"
+```
+
+Or through the CLI, which can upload the result straight into a project:
+
+```sh
+atlas record https://example.com -o checkout.jmx --upload -p SHOP
+```
+
+A browser window opens with a small control panel in the corner. Click through
+your flow, then press **Stop**.
+
+Your recording is saved when you press Stop, when you close the window, and on
+Ctrl+C — closing the window by mistake won't lose it.
+
+## What you get
+
+Each thing you do — a click, a form submit, a page change — becomes a labelled
+**transaction**, with the requests it triggered grouped underneath. A report then
+tells you "Checkout took 3.2s" rather than just listing URLs.
+
+While recording you can:
+
+- **rename** a transaction so the report reads in your language, not the app's URLs
+- **➕ New** to start a new transaction before you click, when one page holds two
+  steps worth measuring separately
+- expand a transaction and **exclude** or **delete** individual requests
+- **⏸ Pause** while you set something up you don't want recorded
+
+## What's kept, and what isn't
+
+**Kept:** the requests your application makes — pages, API calls, form posts.
+
+**Skipped:** images, stylesheets, fonts and known analytics traffic. These
+inflate a load test without telling you anything about your application. Include
+one from the control panel if you need it.
+
+## Dynamic values are handled
+
+If a request sends something it was given earlier — a CSRF token, a session ID,
+an item ID from a search result — the recorder finds where that value came from
+and pulls it out of the live response at run time instead of replaying the
+recorded one. Without this, a recorded plan usually fails on the second run,
+when the token has changed.
+
+Each of these gets a check attached, so if the value ever stops coming back the
+sample fails loudly rather than quietly posting a stale token.
+
+## Adding to an existing plan
+
+Point `-o` at a plan that already exists and the new recording is **added** to it
+as another thread group, leaving what's there untouched. A `.bak` copy is written
+first.
+
+```sh
+atlas-rec record https://example.com -o suite.jmx -n "Checkout"
+atlas-rec record https://example.com -o suite.jmx -n "Search"
+```
+
+## Recording behind a login
+
+**Reuse a signed-in session** — saved when you stop, reloaded next time:
+
+```sh
+atlas-rec record https://app.example.com -o app.jmx --profile ./session.json
+```
+
+**Bring cookies from your own browser** — export them and pass `--cookies`:
+
+```sh
+atlas-rec record https://app.example.com/home -o app.jmx --cookies ./cookies.json
+```
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-o, --out <file>` | Where to write. An existing plan is added to; otherwise created |
+| `-n, --name <name>` | Name for the scenario |
+| `-t, --threads <n>` | Number of users — only when creating a new plan |
+| `-l, --loops <n>` | Iterations per user — only when creating a new plan |
+| `--profile <file>` | Save and reuse a signed-in session |
+| `--cookies <file>` | Start already signed in, using exported cookies |
+| `--correlations <file>` | Pin named parameters to a value of your choosing |
+| `--no-correlate` | Replay recorded values as-is |
+| `--no-timestamps` | Keep recorded timestamps instead of using the current time |
+
+## Check the plan before running it at scale
+
+The recorder captures a single pass through your app. Anything that only appears
+sometimes — a cookie banner, an A/B variant, a retry — is recorded only if it
+happened while you clicked.
+
+When a step redirects, the redirect is followed *and* the destination is recorded
+on its own, so that step can hit the destination twice per iteration. Delete the
+duplicate from the control panel, or from the plan afterwards, if it would skew
+your numbers.
+
+**Think-time pauses** are recorded but switched off, so the plan runs flat out
+until you decide otherwise. Enable the `Settings - Sleeps` block in the plan and
+set the durations you want.
+
+## Driven by an agent, or a script
+
+A recording does not have to be clicked by a person. The same session can be
+controlled command by command — `snapshot` to see the page, `click`, `fill`,
+`tx new` to name the step that follows — which is how an AI assistant records a
+flow for you, and how a script can automate one.
+
+The browser stays visible throughout and your own clicks are recorded too, so
+you can take over for a login and hand it back.
+
+```sh
+atlas-rec start https://shop.example.com -o flow.jmx -n "Checkout"
+atlas-rec snapshot
+atlas-rec tx new "Search"
+atlas-rec click --role button --name "Search"
+atlas-rec stop
+```
+
+See [Your Own Integration](/agents/automation) for the full set, and
+[Atlas for AI Agents](/agents/) to let an assistant do it.

package/dist/docs/results.md

@@ -0,0 +1,79 @@
+# Reading Results
+
+Every run has a dashboard. Open it from a project's **Results** tab, or from the
+test list at `/<project>`.
+
+The dashboard refreshes itself while a test is running, so you can leave it open
+from start to finish.
+
+## Headline numbers
+
+| | |
+|---|---|
+| **Status** | Whether the test is still running |
+| **Test Started** | When it began |
+| **Duration** | How long it has been running, or ran for |
+| **Max Users** | The peak number of concurrent users, added up across every machine |
+| **Req/sec** | Throughput |
+| **Avg Response Time** | Average across the whole test |
+| **Error Rate** | Failed requests as a percentage of all requests, across the whole test |
+
+Each load generator reports its own thread count, and Atlas adds them up. If you
+ran a 100-thread plan on 5 machines, expect roughly 500 — if it shows 100,
+something stopped four of your generators from producing load.
+
+Average response time and error rate are **whole-test** figures, not the last
+few seconds, so they won't jump around as the test finishes.
+
+## The chart
+
+Three series on one timeline:
+
+- **Active Users** (green, right axis) — concurrency over time
+- **Avg. Response Time** (blue, left axis) — how the system responded as load grew
+- **Error Rate %** (red) — when things started failing
+
+Read together, these tell you where your system's limit is: the point where
+response time climbs and errors begin while users are still increasing.
+
+## The aggregation report
+
+One row per request, grouped by thread group, with count, response times
+(average, median, percentiles, min/max), throughput and error percentage.
+
+Every column sorts. Rows are colour-coded:
+
+| | |
+|---|---|
+| **TOTAL** | The whole test |
+| **Thread group** | One per thread group in your plan |
+| **Transaction** | A named step, if your plan uses Transaction Controllers |
+| **Request** | An individual HTTP request |
+
+The same sampler name in two different thread groups stays two separate rows,
+attributed to the right group — so a shared "login" step used by several groups
+doesn't get merged into one misleading number.
+
+### Drilling in
+
+- **Click an Error %** — opens a panel listing the actual errors for that
+  request: response codes and messages, with the full request and response for
+  each distinct failure.
+- **Click a Label** — opens the same chart filtered to that one request, so you
+  can see whether a single endpoint degraded while the rest stayed healthy.
+  There's an error-type dropdown to isolate one specific failure.
+
+## Exporting
+
+**↓ Export Excel** downloads the run as a spreadsheet with the chart and the full
+table, colour-coded to match. Useful for attaching to a report.
+
+## Dark mode
+
+Add `?theme=dark` to any dashboard URL.
+
+## Comparing runs
+
+There is no side-by-side comparison view yet. Name your runs (in the Results
+tab) so you can tell variations apart, and export to Excel to compare them
+outside Atlas.

package/dist/docs/running.md

@@ -0,0 +1,80 @@
+# Running a Test
+
+## From the web interface
+
+Open a project, go to **Run Test**, choose where to run, and press **Run**.
+
+There is no separate deploy step. Atlas reserves the machines, powers on any
+that are switched off, copies the files, and starts JMeter.
+
+## Choosing where it runs
+
+| | |
+|---|---|
+| **Servers** | Pick individual load generators by name. Switched-off machines can still be selected — they are powered on for you. |
+| **Cluster** | Run on a cluster and say how many units you want. Units are created for the test and destroyed afterwards. |
+
+The number of machines multiplies your load: a plan with 100 threads run on 5
+generators applies 500 concurrent users to your system.
+
+Atlas does not divide your thread count across machines — each one runs the plan
+as written. Five generators running a 100-thread plan is 500 users, not 100.
+
+## From the CLI
+
+```bash
+atlas run -p SHOP --jmx checkout.jmx --servers 5 --wait
+```
+
+| | |
+|---|---|
+| `--servers 5` | use any 5 available load generators |
+| `--server gen-01 --server gen-02` | pick specific ones by name |
+| `--cluster my-cluster --units 10` | run on 10 units in a cluster |
+| `--jmx <filename>` | which uploaded plan to run (needed only if the project holds more than one) |
+| `--args "<jmeter args>"` | extra JMeter arguments |
+| `--no-split` | send whole data files to every machine |
+| `--wait` | follow the run and print the report when it finishes |
+| `--timeout 30m` | how long `--wait` waits before giving up (default `2h`) |
+
+## While it runs
+
+The Run Test tab becomes a live view showing each stage — powering on,
+deploying, running — with a **Stop** button.
+
+**Watch** in the sidebar shows live per-machine statistics while a test is in
+progress, which is the quickest way to confirm every generator is actually
+producing load.
+
+From the CLI:
+
+```bash
+atlas status SHOP-20260818-194201
+```
+
+## If a machine is busy
+
+A load generator can only run one test at a time. If you ask for machines that
+are already in use, your run is **queued** and starts when they free up. You
+don't need to retry.
+
+## Stopping a test
+
+Press **Stop**, or:
+
+```bash
+atlas stop SHOP-20260818-194201
+```
+
+Atlas asks JMeter to shut down cleanly so the final results are recorded, and
+only reports the machine as stopped once the process has actually ended.
+
+If a machine can't be reached when you stop a test, Atlas tells you rather than
+pretending it worked, and the run stays open. Retry once the machine is
+reachable — this prevents a test carrying on unnoticed in the background.
+
+## When a test ends
+
+A test ends by itself when the plan says so — a thread group's duration or loop
+count running out. When it does, the machines are released and any that Atlas
+powered on are switched off.