@cloudbeat/atlas-cli 0.4.2 → 0.5.0

package/README.md

@@ -101,9 +101,9 @@ Without it, the command returns as soon as the test has been submitted, and you
 can check on it later:
 
 ```bash
-atlas status SHOP-20260818-194201
-atlas results SHOP-20260818-194201
-atlas stop SHOP-20260818-194201
+atlas status SHOP-20260818-K3F9
+atlas results SHOP-20260818-K3F9
+atlas stop SHOP-20260818-K3F9
 ```
 
 `--jmx` is only needed when a project holds more than one test plan.

package/dist/api.js

@@ -91,7 +91,7 @@ class AtlasApi {
             // 401/403 are almost always a credential problem the user must fix, not a
             // transient failure worth retrying — surface them as usage errors.
             const code = res.status === 401 || res.status === 403 ? ui_1.EXIT.USAGE : ui_1.EXIT.ERROR;
-            throw new ui_1.CliError(`${method} ${routePath} → ${res.status}: ${message}`, code);
+            throw new ui_1.CliError(`${method} ${routePath} → ${res.status}: ${message}`, code, res.status);
         }
         return payload;
     }
@@ -122,12 +122,18 @@ class AtlasApi {
     /** Projects are addressed by name on the CLI; the API wants the id. */
     async projectByName(name) {
         const all = await this.projects();
-        const hit = all.find(p => p.name.toLowerCase() === name.toLowerCase());
-        if (!hit) {
+        const hits = all.filter(p => p.name.toLowerCase() === name.toLowerCase());
+        if (!hits.length) {
             const known = all.map(p => p.name).join(', ') || '(none visible to this token)';
             throw new ui_1.CliError(`No project named "${name}". Available: ${known}`, ui_1.EXIT.USAGE);
         }
-        return hit;
+        // Names are unique within an account, not across them: a login that sees
+        // several accounts can see two. An API token belongs to one account.
+        if (hits.length > 1) {
+            throw new ui_1.CliError(`${hits.length} projects named "${name}" are visible to this login, in different accounts. ` +
+                'Use an API token from the account you mean.', ui_1.EXIT.USAGE);
+        }
+        return hits[0];
     }
     async files(projectId) {
         return this.request('GET', `${this.api}/projects/${projectId}/files`);

package/dist/commands/run.js

@@ -12,6 +12,13 @@ const gates_1 = require("../gates");
 const junit_1 = require("../junit");
 const results_1 = require("./results");
 const TERMINAL = ['done', 'cancelled', 'error'];
+/**
+ * Public dashboards live under /app/public since 2026-10. Older CLIs still print
+ * the root form (/<project>/<testId>); the dashboard redirects it.
+ */
+function dashboardUrl(baseUrl, project, testId) {
+    return `${baseUrl}/app/public/${encodeURIComponent(project)}/${encodeURIComponent(testId)}`;
+}
 /** Pick which load generators to target: explicit names, a count, or a cluster. */
 async function resolveTarget(api, opts) {
     if (opts.cluster) {
@@ -26,25 +33,30 @@ async function resolveTarget(api, opts) {
         }
         return { poolId: hit.id, unitCount, describe: `${unitCount} unit(s) on cluster ${hit.name}` };
     }
+    // A bare count: let Atlas pick N available machines (see submit()).
+    if (!opts.server?.length) {
+        const n = parseInt(opts.servers ?? '1', 10);
+        if (!Number.isFinite(n) || n < 1)
+            throw new ui_1.CliError('--servers must be a positive integer', ui_1.EXIT.USAGE);
+        return { unitCount: n, describe: `${n} machine${n === 1 ? '' : 's'}` };
+    }
     const fleet = await api.servers();
     if (fleet.length === 0) {
         throw new ui_1.CliError('No load generators available to this credential.', ui_1.EXIT.USAGE);
     }
-    if (opts.server?.length) {
-        const wanted = opts.server.flatMap(s => s.split(','));
-        const ids = [];
-        for (const name of wanted.map(w => w.trim()).filter(Boolean)) {
-            const hit = fleet.find(s => s.name.toLowerCase() === name.toLowerCase());
-            if (!hit) {
-                throw new ui_1.CliError(`No server named "${name}". Available: ${fleet.map(s => s.name).join(', ')}`, ui_1.EXIT.USAGE);
-            }
-            ids.push(hit.id);
+    const wanted = opts.server.flatMap(s => s.split(','));
+    const ids = [];
+    for (const name of wanted.map(w => w.trim()).filter(Boolean)) {
+        const hit = fleet.find(s => s.name.toLowerCase() === name.toLowerCase());
+        if (!hit) {
+            throw new ui_1.CliError(`No server named "${name}". Available: ${fleet.map(s => s.name).join(', ')}`, ui_1.EXIT.USAGE);
         }
-        return { serverIds: ids, describe: `${ids.length} server(s)` };
+        ids.push(hit.id);
     }
-    const n = parseInt(opts.servers ?? '1', 10);
-    if (!Number.isFinite(n) || n < 1)
-        throw new ui_1.CliError('--servers must be a positive integer', ui_1.EXIT.USAGE);
+    return { serverIds: ids, describe: `${ids.length} server(s)` };
+}
+/** `--servers <n>` before Atlas could pick by count: the first N visible. */
+function pickFirst(fleet, n) {
     if (n > fleet.length) {
         throw new ui_1.CliError(`Asked for ${n} servers but only ${fleet.length} are available.`, ui_1.EXIT.USAGE);
     }
@@ -101,15 +113,34 @@ function registerRun(program) {
         // rather than silently producing nothing.
         const wait = opts.wait || gates.length > 0 || !!opts.junit;
         const project = await api.projectByName(name);
-        const target = await resolveTarget(api, opts);
-        const submitted = await api.run(project.id, {
-            serverIds: target.serverIds,
-            poolId: target.poolId,
-            unitCount: target.unitCount,
+        let target = await resolveTarget(api, opts);
+        const submit = (t) => api.run(project.id, {
+            serverIds: t.serverIds,
+            poolId: t.poolId,
+            unitCount: t.unitCount,
             jmx: opts.jmx,
             jmeterArgs: opts.args,
             splitCsvs: opts.split,
         });
+        let submitted;
+        try {
+            submitted = await submit(target);
+        }
+        catch (err) {
+            // A bare count that Atlas cannot place: an Atlas from before
+            // count-based runs ("serverIds array … required"), or an account whose
+            // machines span several pools ("Say which machines"). Fall back to
+            // choosing the first N visible servers, as this CLI always did.
+            const bareCount = target.unitCount != null && target.poolId == null && !target.serverIds;
+            if (!(bareCount && err instanceof ui_1.CliError && err.httpStatus === 400
+                && /serverIds array|Say which machines/.test(err.message)))
+                throw err;
+            const fleet = await api.servers();
+            if (fleet.length === 0)
+                throw new ui_1.CliError('No load generators available to this credential.', ui_1.EXIT.USAGE);
+            target = pickFirst(fleet, target.unitCount);
+            submitted = await submit(target);
+        }
         if (!opts.json) {
             ui_1.log.ok(submitted.status === 'queued'
                 ? `Queued (position ${submitted.position ?? '?'}) — servers are busy with another run.`
@@ -121,7 +152,7 @@ function registerRun(program) {
             if (opts.json)
                 console.log(JSON.stringify(submitted, null, 2));
             else if (submitted.testId) {
-                ui_1.log.dim(`dashboard: ${api.baseUrl}/${project.name}/${submitted.testId}`);
+                ui_1.log.dim(`dashboard: ${dashboardUrl(api.baseUrl, project.name, submitted.testId)}`);
             }
             return;
         }
@@ -162,7 +193,7 @@ function registerRun(program) {
                 else
                     ui_1.log.error(chalk_1.default.bold('gate ') + (0, gates_1.formatGate)(r));
             }
-            ui_1.log.dim(`dashboard: ${api.baseUrl}/${project.name}/${entry.testId}`);
+            ui_1.log.dim(`dashboard: ${dashboardUrl(api.baseUrl, project.name, entry.testId)}`);
         }
         const failed = results.filter(r => !r.passed);
         if (failed.length) {

package/dist/docs/automation.md

@@ -9,7 +9,7 @@ and everything it does is scriptable.
 ```sh
 atlas projects --json
 atlas capacity --json
-atlas results SHOP-20260917-101500 --json
+atlas results SHOP-20260917-7QKD --json
 ```
 
 Every command takes `--json`. On failure it prints the error as JSON on

package/dist/docs/commands.md

@@ -72,10 +72,10 @@ the test ID.
 ## Checking on a run
 
 ```sh
-atlas status SHOP-20260818-194201
-atlas results SHOP-20260818-194201
-atlas results SHOP-20260818-194201 --json
-atlas stop SHOP-20260818-194201
+atlas status SHOP-20260818-K3F9
+atlas results SHOP-20260818-K3F9
+atlas results SHOP-20260818-K3F9 --json
+atlas stop SHOP-20260818-K3F9
 ```
 
 `results` prints the aggregation report — one row per request, plus totals.
@@ -105,9 +105,9 @@ and GUI listeners left switched on.
 
 ```sh
 atlas tests -p SHOP --limit 10          # recent runs, newest first
-atlas timeseries SHOP-20260818-194201   # users, response time and errors over time
-atlas errors SHOP-20260818-194201       # every distinct error, with its share
-atlas errors SHOP-20260818-194201 --full --label "01.01 /home"
+atlas timeseries SHOP-20260818-K3F9   # users, response time and errors over time
+atlas errors SHOP-20260818-K3F9       # every distinct error, with its share
+atlas errors SHOP-20260818-K3F9 --full --label "01.01 /home"
 ```
 
 `timeseries` shows the shape of a run — where users peaked and where response

package/dist/docs/index.json

@@ -26,7 +26,7 @@
   {
     "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>`.",
+    "summary": "Every run has a dashboard. Open it from a project's **Results** tab, or from the test list at `/app/public/<project>`.",
     "source": "guide/results.md"
   },
   {

package/dist/docs/projects.md

@@ -18,8 +18,8 @@ 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
+doing when you run variations against each other, since `SHOP-20260818-K3F9`
+tells you which day a run happened but not what it was for. "Baseline, 500 users" is
 easier to find three weeks later.
 
 ### Files

package/dist/docs/recorder.md

@@ -50,7 +50,10 @@ While recording you can:
 
 ## What's kept, and what isn't
 
-**Kept:** the requests your application makes — pages, API calls, form posts.
+**Kept:** the requests your application makes — pages, API calls, form posts —
+and the CORS preflight a browser sends before calling an API on another domain.
+Preflights are marked `(OPTIONS)` and recorded once per address, the way a real
+visitor's browser sends them.
 
 **Skipped:** images, stylesheets, fonts and known analytics traffic. These
 inflate a load test without telling you anything about your application. Include
@@ -64,9 +67,32 @@ 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.
 
+This covers values wherever they are sent and wherever they came from:
+
+- in the query, a form, a JSON body or a header;
+- **inside the address itself** — the cart or order your session created, as in
+  `/cart/{id}/items/{id}`. Only parts of the address that are clearly generated
+  IDs are touched, and only when your application's API returned them; the fixed
+  parts of an address never are;
+- from a response body, a response header, or a redirect on the way.
+
 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.
 
+## Errors you meant to get
+
+A request that answered with an error while you recorded — "who am I?" returning
+401 before you signed in — is part of the flow, not a failure. The plan expects
+that same status and checks for it, so it doesn't count as an error, while a
+different code (a 500 where a 401 was recorded) still fails the sample.
+
+## Every page is checked by its title
+
+When a page you visited had a title, the plan checks the same title comes back on
+every run, so a login screen or error page served in place of the real one fails
+the sample instead of counting as a success. If your titles change from run to run
+(a user name, a date), record with `--no-title-assertions`.
+
 ## Adding to an existing plan
 
 Point `-o` at a plan that already exists and the new recording is **added** to it
@@ -105,6 +131,7 @@ atlas-rec record https://app.example.com/home -o app.jmx --cookies ./cookies.jso
 | `--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 |
+| `--no-title-assertions` | Don't check that each page returns its recorded title |
 
 ## Check the plan before running it at scale
 
@@ -117,6 +144,11 @@ 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.
 
+Start from a browser that has never visited the site, or sign out and clear the
+site's data first. A browser that has been there before can carry things over —
+a cart it remembers, a stored sign-in token — and the recording then depends on
+them, while every simulated user starts from nothing.
+
 **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.

package/dist/docs/results.md

@@ -1,7 +1,7 @@
 # Reading Results
 
 Every run has a dashboard. Open it from a project's **Results** tab, or from the
-test list at `/<project>`.
+test list at `/app/public/<project>`.
 
 The dashboard refreshes itself while a test is running, so you can leave it open
 from start to finish.

package/dist/docs/running.md

@@ -49,7 +49,7 @@ producing load.
 From the CLI:
 
 ```bash
-atlas status SHOP-20260818-194201
+atlas status SHOP-20260818-K3F9
 ```
 
 ## If a machine is busy
@@ -63,7 +63,7 @@ don't need to retry.
 Press **Stop**, or:
 
 ```bash
-atlas stop SHOP-20260818-194201
+atlas stop SHOP-20260818-K3F9
 ```
 
 Atlas asks JMeter to shut down cleanly so the final results are recorded, and

package/dist/docs/troubleshooting.md

@@ -73,7 +73,20 @@ Usually a dynamic value that wasn't correlated — a token that was valid when y
 recorded and isn't now. Re-record with correlation enabled (the default), and
 check that the step which issues the token is part of the recording.
 
+If the value is sent but never appeared in an earlier response, the browser
+brought it with it — a cart or sign-in token remembered from a previous visit.
+Record again from a browser with no history for the site.
+
+## Every request gets a blank page or a "Request Not Allowed" response
+
+The site is protected against bots, and the load generators look like one. The
+recorder's browser can be turned away the same way. This is not something to work
+around in the plan: ask the site's owner to allow the load generators' addresses
+(and yours, for recording), or to give you a test environment without the
+protection. A captcha on sign-in needs the same treatment — a recorded captcha
+answer is single-use and expires within minutes.
+
 ## Getting help
 
-When reporting a problem, include the **test ID** (`SHOP-20260818-194201`). It
+When reporting a problem, include the **test ID** (`SHOP-20260818-K3F9`). It
 identifies the run and everything recorded about it.

package/dist/skills/atlas-correlate/SKILL.md

@@ -32,7 +32,32 @@ Judge them:
 - A value that is sent but appears in **no** earlier response → the recorder
   cannot correlate it, and it is exactly the kind that breaks. Find out what it
   is: generated in the browser (a timestamp, a random id, a fingerprint), or
-  supposed to vary per user (a login, an account number).
+  supposed to vary per user (a login, an account number), or **left over from an
+  earlier visit** — a cart id or bearer token the browser had stored. The last
+  kind means the recording was not made as a first-time visitor; the clean fix is
+  to record again from a browser with no history for the site.
+
+What the recorder covers, so you know where to look for gaps:
+
+- Values in the query, a form, a JSON body, dynamic headers, and **generated IDs
+  in the URL path** (`/cart/{uuid}`) — paths only for UUIDs, long hex or opaque
+  tokens that an API JSON response or a response header returned.
+- Sources in a response body, a response header (matched case-insensitively), or
+  the first hop of a redirect (the extractor covers sub-samples).
+
+What it does not:
+
+- **A list sent back joined** (`uuid_list=a,b,c` built from a JSON array). Add a
+  JSON Extractor on the array with match number `-1` and *Compute concatenation
+  var* on, and send `${name_ALL}`. If the array can be empty, put the consuming
+  request under an If Controller on `${name_matchNr}` — the application would
+  not make that call at all.
+- **Values the user chose** — a search term, a date, a city. These are input, not
+  correlation; if the recorder tied one to a tracker's response, make it a literal
+  or a CSV column.
+- **Browser-generated security data** — a bot-protection sensor post, a captcha
+  token. Do not correlate or replay these; they need the site owner to exempt the
+  load generators.
 
 ## Pin the rest yourself
 

package/dist/skills/atlas-record/SKILL.md

@@ -152,6 +152,13 @@ The same capture always produces the same plan, so this is safe to repeat.
 
 ## Things that will bite you
 
+- **A blank page or "Request Not Allowed" on the first load** means the site's
+  bot protection turned the recorder's browser away. Stop and tell the person.
+  Never try to get past it — it is the site owner's control, and the load test
+  will meet it too. The fix is for the owner to allow the person's addresses.
+- **Record as a first-time visitor.** A browser with history for the site can
+  bring a stored cart or sign-in token along, and the recording then depends on
+  it. Check `suggest` for values that appear in no earlier response.
 - **Never trigger a native dialog** (`alert`, `confirm`, a file picker). They
   block the browser and the session stops responding. Avoid clicking anything
   that might delete or confirm.

package/dist/ui.js

@@ -24,9 +24,12 @@ exports.EXIT = {
 /** Thrown for expected failures — reported without a stack trace. */
 class CliError extends Error {
     code;
-    constructor(message, code = exports.EXIT.ERROR) {
+    httpStatus;
+    /** `httpStatus`: the API's status when the error is an API refusal. */
+    constructor(message, code = exports.EXIT.ERROR, httpStatus) {
         super(message);
         this.code = code;
+        this.httpStatus = httpStatus;
         this.name = 'CliError';
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbeat/atlas-cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Atlas CLI — run JMeter load tests from CI and record scenarios",
   "main": "dist/cli.js",
   "bin": {