@bloom-perf/yaml-pptr 2.0.2 → 3.1.0

package/README.md

@@ -11,9 +11,11 @@
 ## Installation
 
 ```bash
-npm install @bloom-perf/yaml-pptr
+npm install @bloom-perf/yaml-pptr puppeteer
 ```
 
+`puppeteer` is a peer dependency (`^25.0.0`): your project controls its version.
+
 ## Quick Start
 
 ```typescript
@@ -108,7 +110,93 @@ readYamlAndInterpret(yaml)
 ### 3. Run it
 
 ```bash
-npx ts-node src/runner.ts
+npx tsx src/runner.ts
+```
+
+## API Options
+
+```typescript
+await readYamlAndInterpret(yaml, {
+  headless: true,          // default: true
+  launchOptions: {         // extra Puppeteer launch options, per browser
+    firefox: { executablePath: '/path/to/firefox' },
+  },
+  browsers: { chrome: myBrowser }, // reuse already launched browsers (not closed)
+  logger: myLogger,
+  onPage: async (page, ctx) => { /* page hook */ },
+});
+```
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `headless` | `true` | Run launched browsers headless |
+| `launchOptions` | `{}` | Puppeteer `LaunchOptions` per browser; `args` are appended to the defaults |
+| `browsers` | `{}` | Pre-launched browsers to use instead of launching new ones |
+| `logger` | console | Custom logger (`debug`, `info`, `warn`, `error`) |
+| `onPage` | - | Callback invoked on every new page with `{ scenarioName, workerIndex, iteration }` |
+
+### Firefox
+
+Puppeteer drives Firefox through WebDriver BiDi, which requires a recent Firefox. Install the version matching your Puppeteer release with:
+
+```bash
+npx puppeteer browsers install firefox
+```
+
+To use another Firefox installed on the machine, pass its path with `launchOptions.firefox.executablePath`.
+
+### Error handling
+
+The configuration is fully checked before anything runs: YAML syntax, schema (an unknown key such as a typo is an error), and environment variables. If it is invalid, `readYamlAndInterpret` rejects with a `ConfigurationError` listing every problem with its location, and no browser page is opened:
+
+```text
+ConfigurationError: Invalid scenario configuration:
+✖ Unrecognized key: "iteration"
+  → at scenarios[0]
+✖ Invalid input: expected int, received number
+  → at scenarios[0].workers
+```
+
+Then every scenario, worker and iteration always runs to completion: a failed iteration does not stop the next iterations nor the other workers, and its page is always closed. If anything failed, `readYamlAndInterpret` then rejects with an `AggregateError` whose `errors` contain:
+
+- `WorkerError` — an iteration failed (`scenarioName`, `workerIndex`, `iteration`, original error in `cause`)
+- `BrowserLaunchError` — a browser could not be launched (`browser`, original error in `cause`)
+
+```typescript
+import { readYamlAndInterpret, ConfigurationError } from '@bloom-perf/yaml-pptr';
+
+try {
+  await readYamlAndInterpret(yaml);
+} catch (e) {
+  if (e instanceof ConfigurationError) {
+    console.error(e.message); // invalid YAML, unknown key, missing variable...
+  } else if (e instanceof AggregateError) {
+    for (const err of e.errors) console.error(err.message); // WorkerError / BrowserLaunchError
+  }
+  process.exit(1);
+}
+```
+
+## Editor Support
+
+The package ships a JSON Schema of the YAML configuration (`dist/schema.json`), generated from the very schema used to validate it at runtime. With the [YAML extension for VS Code](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) (or any editor using `yaml-language-server`), you get completion, documentation on hover, and errors (unknown key, wrong type...) while typing.
+
+Add this first line to a scenario file:
+
+```yaml
+# yaml-language-server: $schema=https://unpkg.com/@bloom-perf/yaml-pptr@3/dist/schema.json
+scenarios:
+  - name: Login
+```
+
+With the package installed, a local path works too (relative to the YAML file), e.g. `$schema=../node_modules/@bloom-perf/yaml-pptr/dist/schema.json`. To apply it to several files, map them in `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://unpkg.com/@bloom-perf/yaml-pptr@3/dist/schema.json": ["scenarios/*.yaml"]
+  }
+}
 ```
 
 ## YAML Reference
@@ -119,13 +207,37 @@ npx ts-node src/runner.ts
 | -------- | ---- | ------- | ----------- |
 | `name` | string | `Scenario N` | Scenario name |
 | `browser` | `chrome` \| `firefox` | `chrome` | Browser to use |
-| `run` | `PARALLEL` \| `SEQUENTIAL` | `PARALLEL` | Worker start strategy |
-| `initialDelaySeconds` | number | `0` | Delay before starting |
-| `workers` | number | `1` | Number of parallel workers |
-| `iterations` | number | `1` | Repetitions per worker |
+| `run` | `PARALLEL` \| `SEQUENTIAL` | `PARALLEL` | Worker start strategy: `PARALLEL` starts all workers after `initialDelaySeconds`; `SEQUENTIAL` starts worker *n* after *n* × `initialDelaySeconds` |
+| `initialDelaySeconds` | number | `0` | Start delay, applied once per worker before its first iteration (see `run`) |
+| `workers` | integer ≥ 1 | `1` | Number of parallel workers |
+| `iterations` | integer ≥ 1 | `1` | Repetitions per worker |
 | `location` | string | - | Starting URL |
-| `steps` | array | - | Simplified syntax |
-| `actions` | array | - | Full syntax with options |
+| `steps` | array | - | Simplified syntax (full actions are accepted too) |
+| `actions` | array | - | Full syntax with options, run after `steps` |
+
+All the scenarios of a file start at the same time, whatever their browser: each one is a population of users with its own `workers`, `iterations` and start strategy. Unknown keys are rejected (see [Error handling](#error-handling)).
+
+### Selectors
+
+Every selector (`click`, `input`, `CLICK`, `TYPE`, `WAIT_FOR_SELECTOR`) accepts a CSS selector or any [Puppeteer selector](https://pptr.dev/guides/page-interactions), so XPath, text and ARIA queries need no special syntax:
+
+| Kind | Example |
+| ---- | ------- |
+| CSS | `#login-button`, `form .submit` |
+| XPath | `::-p-xpath(//button[@type='submit'])` or `xpath///button[@type='submit']` |
+| Text | `::-p-text(Sign in)` |
+| ARIA | `::-p-aria(Sign in)`, `::-p-aria([name="Sign in"][role="button"])` |
+| Shadow DOM | `my-app >>> button` (any depth), `my-app >>>> button` (direct shadow root) |
+
+```yaml
+steps:
+  - input:
+      selector: "::-p-xpath(//input[@name='email'])"
+      text: "${APP_USER}"
+  - click: "::-p-text(Sign in)"
+```
+
+`${VAR}` placeholders are resolved in selectors too.
 
 ### Steps (Simplified Syntax)
 
@@ -164,7 +276,17 @@ npx ts-node src/runner.ts
 
 ### Actions (Full Syntax)
 
-Use `actions` instead of `steps` when you need advanced options.
+Use the full syntax when you need advanced options. Full actions can be listed in `actions` (run after `steps`), or written directly among `steps` to mix both syntaxes in the order you need:
+
+```yaml
+steps:
+  - click: "#open-menu"
+  - type: WAIT_FOR_SELECTOR
+    selector: ".menu"
+    options:
+      visible: true
+  - click: ".menu .logout"
+```
 
 #### GOTO
 
@@ -248,6 +370,8 @@ Use `actions` instead of `steps` when you need advanced options.
   script: "document.title"
 ```
 
+The script is never interpolated with environment variables (injecting values into code would be unsafe).
+
 #### SET_VIEWPORT
 
 ```yaml
@@ -262,6 +386,8 @@ Use `actions` instead of `steps` when you need advanced options.
 - type: PAUSE  # Press Enter to continue
 ```
 
+Meant for debugging in an interactive terminal. When there is none (CI, container, piped input), the PAUSE is ignored with a warning instead of blocking forever.
+
 #### CLOSE
 
 ```yaml
@@ -270,19 +396,37 @@ Use `actions` instead of `steps` when you need advanced options.
 
 ## Environment Variables
 
-Use `$VAR_NAME` syntax in `location` or `navigate`:
+Keep URLs and credentials out of the YAML with `${VAR_NAME}` placeholders. They are resolved before anything runs: a missing variable is a `ConfigurationError`.
 
 ```yaml
-location: "$BASE_URL"
+scenarios:
+  - name: Login
+    location: "${BASE_URL}/login"
+    steps:
+      - input:
+          selector: "#username"
+          text: "${APP_USER}"
+      - input:
+          selector: "#password"
+          text: "${APP_PASSWORD}"
+      - click: "#login-button"
 ```
 
 ```bash
-BASE_URL=https://example.com npx ts-node runner.ts
+BASE_URL=https://example.com APP_USER=alice APP_PASSWORD=... npx tsx runner.ts
 ```
 
+| Syntax | Where | Notes |
+| ------ | ----- | ----- |
+| `${VAR}` | Anywhere in `location`, `navigate`, GOTO `url`/`referer`, selectors, typed `text`, SCREENSHOT `path` | `$${` produces a literal `${` |
+| `$VAR` | As the whole value of `location`, `navigate`, GOTO `url`, SCREENSHOT `path` | Elsewhere a `$` is kept as is (e.g. a password like `$ecret`) |
+| `$VAR[workerIndex]` | As the whole value of `location`, `navigate` | One value per worker, see below |
+
+`EVALUATE` scripts are never interpolated. Typed texts and resolved values are never logged.
+
 ### Indexed Variables
 
-Assign different values to each worker using `$VAR[workerIndex]`:
+Assign different values to each worker using `$VAR[workerIndex]` (comma-separated values). There must be at least one non-empty value per worker, otherwise it is a `ConfigurationError`:
 
 ```yaml
 scenarios:
@@ -294,7 +438,7 @@ scenarios:
 ```
 
 ```bash
-URLS="https://site1.com,https://site2.com,https://site3.com" npx ts-node runner.ts
+URLS="https://site1.com,https://site2.com,https://site3.com" npx tsx runner.ts
 ```
 
 Worker 0 gets `site1.com`, worker 1 gets `site2.com`, etc.
@@ -324,6 +468,9 @@ npm test
 # Run tests with coverage
 npm run test:coverage
 
+# Type check
+npm run typecheck
+
 # Build
 npm run build
 ```

package/dist/core/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Raised before anything runs when the configuration is invalid: YAML syntax,
+ * schema validation (unknown key, wrong type...) or environment variable
+ * resolution (missing variable, not enough per-worker values...).
+ */
+export declare class ConfigurationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Raised when an iteration of a scenario worker fails. Carries the scenario
+ * name, the worker index and the iteration so the caller knows exactly where
+ * the failure happened.
+ */
+export declare class WorkerError extends Error {
+    readonly scenarioName: string;
+    readonly workerIndex: number;
+    readonly iteration: number;
+    constructor(scenarioName: string, workerIndex: number, iteration: number, cause: unknown);
+}
+/**
+ * Raised when a browser could not be launched (missing binary, bad options...).
+ */
+export declare class BrowserLaunchError extends Error {
+    readonly browser: string;
+    constructor(browser: string, cause: unknown);
+}

package/dist/core/model.d.ts

@@ -103,7 +103,7 @@ export interface CloseAction extends BaseAction {
 }
 export interface EvaluateAction extends BaseAction {
     actionType: ActionType.Evaluate;
-    script: string | ((...args: any[]) => any);
+    script: string;
 }
 export interface SetViewportAction extends BaseAction {
     actionType: ActionType.SetViewport;

package/dist/index.d.ts

@@ -1,12 +1,32 @@
 import * as p from 'puppeteer';
-import { SupportedBrowser, OnPageCallback } from './core/model';
-import { YpLogger } from './core/logger';
-export type { ScenarioContext, OnPageCallback } from './core/model';
+import { SupportedBrowser, OnPageCallback } from './core/model.js';
+import { YpLogger } from './core/logger.js';
+export type { ScenarioContext, OnPageCallback } from './core/model.js';
+export { WorkerError, BrowserLaunchError, ConfigurationError } from './core/errors.js';
 export type ReadYamlOptions = {
+    /** Already launched browsers to use instead of launching new ones. They are not closed. */
     browsers?: {
         [key in SupportedBrowser]?: p.Browser;
     };
     logger?: YpLogger;
     onPage?: OnPageCallback;
+    /** Run launched browsers in headless mode. Defaults to `true`. */
+    headless?: boolean;
+    /** Extra Puppeteer launch options per browser (e.g. `executablePath`). `args` are appended to the defaults. */
+    launchOptions?: {
+        [key in SupportedBrowser]?: p.LaunchOptions;
+    };
 };
+/**
+ * Parses and validates the YAML, resolves environment variables, then runs
+ * every scenario. All scenarios start at the same time (each one with its own
+ * workers and start strategy), whatever the browser they target.
+ *
+ * - An invalid configuration (YAML syntax, unknown key, missing environment
+ *   variable...) rejects with a `ConfigurationError` before anything runs.
+ * - Otherwise all scenarios are always run to completion. If anything failed
+ *   (browser launch or iteration), the promise rejects with an `AggregateError`
+ *   whose `errors` are `BrowserLaunchError` / `WorkerError` instances, in
+ *   scenario order.
+ */
 export declare const readYamlAndInterpret: (yamlContent: string, options?: ReadYamlOptions) => Promise<void>;

package/dist/index.js

@@ -1 +1,2 @@
-import*as x from"puppeteer";import*as k from"js-yaml";import*as t from"zod";var T=t.enum(["load","domcontentloaded","networkidle0","networkidle2"]),R=t.enum(["left","right","middle"]),P=t.enum(["chrome","firefox"]),F=t.object({timeout:t.number().optional(),waitUntil:t.union([T,T.array()]).optional(),referer:t.string().optional()}).optional(),L=t.object({type:t.literal("WAIT"),milliseconds:t.number()}),B=t.object({button:R.optional(),clickCount:t.number().optional(),delay:t.number().optional()}).optional(),j=t.object({delay:t.number().optional()}).optional(),U=t.object({visible:t.boolean().optional(),hidden:t.boolean().optional(),timeout:t.number().optional()}).optional(),V=t.object({type:t.enum(["png","jpeg"]).optional(),quality:t.number().optional(),fullPage:t.boolean().optional(),clip:t.object({x:t.number(),y:t.number(),width:t.number(),height:t.number()}).optional(),omitBackground:t.boolean().optional(),encoding:t.enum(["base64","binary"]).optional()}).optional(),_=t.object({type:t.literal("GOTO"),url:t.string(),options:F}),G=t.object({type:t.literal("CLICK"),selector:t.string(),options:B}),I=t.object({type:t.literal("TYPE"),selector:t.string(),text:t.string(),options:j}),N=t.object({type:t.literal("WAIT_FOR_SELECTOR"),selector:t.string(),options:U}),M=t.object({type:t.literal("WAIT_FOR_TIMEOUT"),timeout:t.number()}),D=t.object({type:t.literal("PAUSE")}),q=t.object({type:t.literal("SCREENSHOT"),path:t.string(),options:V}),H=t.object({type:t.literal("EVALUATE"),script:t.union([t.string(),t.function()])}),K=t.object({type:t.literal("SET_VIEWPORT"),width:t.number(),height:t.number()}),J=t.object({type:t.literal("CLOSE")}),z=[_,G,I,N,M,D,q,H,K,J,L];if(z.length===0)throw new Error("Le tableau des sch\xE9mas d'actions est vide.");var Q=z,Z=t.discriminatedUnion("type",Q),X=t.object({navigate:t.string()}),Y=t.literal("waitForever"),tt=t.object({wait:t.number()}),et=t.object({click:t.string()}),ot=t.object({input:t.object({selector:t.string(),text:t.string()})}),it=t.union([X,Y,tt,et,ot]),nt=t.object({name:t.string().optional(),browser:P.optional(),run:t.enum(["PARALLEL","SEQUENTIAL"]).optional(),initialDelaySeconds:t.number().nonnegative().optional(),workers:t.number().positive().optional(),iterations:t.number().positive().optional(),location:t.string().optional(),steps:t.array(it).optional(),actions:t.array(Z).optional()}),$=t.object({scenarios:t.array(nt)});var E=i=>{let e=k.load(i);return $.parse(e)};var A={debug(i){console.log(i)},info(i){console.log(i)},warn(i){console.log(i)},error(i){console.error(i)}};var w=class{envVarResolve;logger;constructor(e,n=A){this.envVarResolve=o=>{let r=o.startsWith("$")?o.substring(1):o;return e(r)},this.logger=n}resolve(e){return{scenarios:e.scenarios.map((n,o)=>this.resolveScenario(n,o+1))}}resolveScenario(e,n){this.logger.debug(`Resolving YAML scenario: ${JSON.stringify(e)}`);let o=[];e.location&&o.push(this.createNavigateAction(e.location)),e.steps&&o.push(...e.steps.map(s=>this.resolveStep(s))),e.actions&&o.push(...e.actions.map(s=>this.resolveAction(s)));let r=e.run==="SEQUENTIAL"?{delaySecondsBetweenWorkerInits:e.initialDelaySeconds||0}:{initialDelaySeconds:e.initialDelaySeconds||0};return{name:e.name||`Scenario ${n}`,browser:e.browser||"chrome",run:r,workers:e.workers||1,iterations:e.iterations||1,actions:o}}resolveStep(e){if(e==="waitForever")return this.logger.debug("Resolving step: waitForever"),{actionType:"WaitForever"};if("wait"in e)return this.logger.debug(`Resolving step: wait ${e.wait} seconds`),{actionType:"Wait",milliseconds:e.wait*1e3};if("navigate"in e)return this.logger.debug("Resolving step: navigate"),this.createNavigateAction(e.navigate);if("click"in e)return this.logger.debug(`Resolving step: click "${e.click}"`),{actionType:"CLICK",selector:e.click};if("input"in e)return this.logger.debug(`Resolving step: input into "${e.input.selector}"`),{actionType:"TYPE",selector:e.input.selector,text:e.input.text};throw new Error(`Unknown step format: ${JSON.stringify(e)}`)}resolveAction(e){switch(this.logger.debug(`Resolving action: ${JSON.stringify(e)}`),e.type){case"GOTO":return{actionType:"GOTO",url:this.resolveStringOrEnv(e.url),options:e.options};case"WAIT":return{actionType:"Wait",milliseconds:e.milliseconds*1e3};case"CLICK":return{actionType:"CLICK",selector:e.selector,options:e.options};case"TYPE":return{actionType:"TYPE",selector:e.selector,text:e.text,options:e.options};case"WAIT_FOR_SELECTOR":return{actionType:"WAIT_FOR_SELECTOR",selector:e.selector,options:e.options};case"WAIT_FOR_TIMEOUT":return{actionType:"WAIT_FOR_TIMEOUT",timeout:e.timeout};case"PAUSE":return{actionType:"PAUSE"};case"SCREENSHOT":return{actionType:"SCREENSHOT",path:this.resolveStringOrEnv(e.path),options:e.options};case"EVALUATE":return{actionType:"EVALUATE",script:e.script};case"SET_VIEWPORT":return{actionType:"SET_VIEWPORT",width:e.width,height:e.height};case"CLOSE":return{actionType:"CLOSE"};default:return e}}createNavigateAction(e){return{actionType:"Navigate",location:this.resolveUrlOrEnv(e)}}resolveUrlOrEnv(e){let n="[workerIndex]";if(e.startsWith("$")){if(e.endsWith(n)){this.logger.debug(`Resolving indexed environment variable: "${e}"`);let o=e.substring(1,e.length-n.length);return{workerIndex:this.envVarResolve(o).split(",").map(c=>c.trim())}}return this.logger.debug(`Resolving environment variable: "${e}"`),{url:this.envVarResolve(e.substring(1))}}return this.logger.debug(`Using direct URL: "${e}"`),{url:e}}resolveStringOrEnv(e){return e.startsWith("$")?(this.logger.debug(`Resolving environment variable: "${e}"`),this.envVarResolve(e.substring(1))):e}};function st(i,e){let n=e||"png";return i.endsWith(".png")||i.endsWith(".jpeg")||i.endsWith(".jpg")||i.endsWith(".webp")?i:`${i}.${n}`}var W=async(i,e,n=A,o)=>await at(e.workers,e.name,async r=>{for(let s=0;s<e.iterations;s++){let c=e.run;"delaySecondsBetweenWorkerInits"in c?(n.info(`Scenario "${e.name}" (worker ${r}) > Choosing SEQUENTIAL start with ${c.delaySecondsBetweenWorkerInits} seconds between workers`),await new Promise(u=>setTimeout(u,c.delaySecondsBetweenWorkerInits*r*1e3))):(n.info(`Scenario "${e.name}" (worker ${r}) > Choosing PARALLEL start with ${c.initialDelaySeconds} seconds of initial delay`),await new Promise(u=>setTimeout(u,c.initialDelaySeconds*1e3)));let l=await i.newPage();o&&await o(l,{scenarioName:e.name,workerIndex:r,iteration:s}),await ct(e.name,e.actions,l,r,n),await l.close()}},n),at=async(i,e,n,o=A)=>Promise.all(Array.from({length:i},async(r,s)=>{try{o.info(`Scenario "${e}" (worker ${s}) started.`),await n(s)}catch(c){o.error(`Scenario ${e} (worker ${s}) failed: ${c}`)}})),ct=async(i,e,n,o,r=A)=>{for(let s of e){let{actionType:c}=s;switch(c){case"Navigate":let l=s;"url"in l.location?(r.info(`Scenario "${i}" (worker ${o}) > Navigating to location "${l.location.url}"`),await n.goto(l.location.url)):(r.info(`Scenario "${i}" (worker ${o}) > Navigating to indexed location "${l.location.workerIndex[o]}"`),await n.goto(l.location.workerIndex[o]));break;case"Wait":let u=s;r.info(`Scenario "${i}" (worker ${o}) > Waiting ${u.milliseconds} milliseconds...`),await n.evaluate(y=>new Promise(f=>setTimeout(f,y)),u.milliseconds);break;case"WaitForever":for(r.info(`Scenario "${i}" (worker ${o}) > Waiting forever...`);;)await new Promise(y=>setTimeout(y,3600*1e3));break;case"GOTO":let d=s;r.info(`Scenario "${i}" (worker ${o}) > GOTO "${d.url}"`);let v={timeout:d.options?.timeout,waitUntil:d.options?.waitUntil,referer:d.options?.referer};await n.goto(d.url,v);break;case"CLICK":let a=s;r.info(`Scenario "${i}" (worker ${o}) > CLICK on "${a.selector}"`);let g={button:a.options?.button,clickCount:a.options?.clickCount,delay:a.options?.delay};await n.click(a.selector,g);break;case"TYPE":let S=s;r.info(`Scenario "${i}" (worker ${o}) > TYPE into "${S.selector}"`),await n.type(S.selector,S.text,S.options);break;case"WAIT_FOR_SELECTOR":let m=s;r.info(`Scenario "${i}" (worker ${o}) > WAIT_FOR_SELECTOR "${m.selector}"`),await n.waitForSelector(m.selector,m.options);break;case"WAIT_FOR_TIMEOUT":let h=s;r.info(`Scenario "${i}" (worker ${o}) > WAIT_FOR_TIMEOUT ${h.timeout} milliseconds`),await n.evaluate(y=>new Promise(f=>setTimeout(f,y)),h.timeout);break;case"PAUSE":r.info(`Scenario "${i}" (worker ${o}) > PAUSE, press Enter to continue...`),await new Promise(y=>{process.stdin.resume(),process.stdin.once("data",()=>{process.stdin.pause(),y()})});break;case"SCREENSHOT":let p=s;r.info(`Scenario "${i}" (worker ${o}) > SCREENSHOT "${p.path}"`);let O={path:st(p.path,p.options?.type),type:p.options?.type,quality:p.options?.quality,fullPage:p.options?.fullPage,clip:p.options?.clip,omitBackground:p.options?.omitBackground,encoding:p.options?.encoding};await n.screenshot(O);break;case"EVALUATE":let C=s;r.info(`Scenario "${i}" (worker ${o}) > EVALUATE script`),await n.evaluate(C.script);break;case"SET_VIEWPORT":let b=s;r.info(`Scenario "${i}" (worker ${o}) > SET_VIEWPORT width=${b.width}, height=${b.height}`),await n.setViewport({width:b.width,height:b.height});break;case"CLOSE":r.info(`Scenario "${i}" (worker ${o}) > CLOSE page`),await n.close();break;default:throw new Error(`Unhandled action type "${c}" while evaluating scenario "${i}" on worker ${o}`)}}};var re=async(i,e={})=>{let{browsers:n={},logger:o=A,onPage:r}=e,s=E(i),l=new w(a=>{let g=process.env[a];if(o.debug(`Resolving env variable "${a}" with value ***`),g)return g;throw new Error(`Tried to resolve env variable ${a} but was empty.`)},o).resolve(s),u={};for(let a of l.scenarios){let g=a.browser||"chrome";u[g]||(u[g]=[]),u[g]?.push(a)}let d=["chrome","firefox"],v=Object.entries(u).map(async([a,g])=>{if(!g)return;if(!d.includes(a)){console.error(`Navigateur non support\xE9: ${a}. Les navigateurs support\xE9s sont: ${d.join(", ")}`);return}let S=["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage","--disable-accelerated-2d-canvas","--disable-gpu","--ignore-certificate-errors"];a==="chrome"&&S.push("--start-maximized"),a==="firefox"&&S.push("--private");let m=n[a],h=!1;m||(m=await x.launch({headless:!1,channel:a,acceptInsecureCerts:!0,args:S}),h=!0);try{for(let p of g)await W(m,p,o,r)}catch(p){console.error(`Erreur lors de l'ex\xE9cution des sc\xE9narios pour ${a}:`,p)}finally{h&&m&&await m.close()}});await Promise.all(v)};export{re as readYamlAndInterpret};
+import*as F from"js-yaml";import*as _ from"zod";import*as t from"zod";var y=t.number().int().nonnegative(),v=t.number().int().positive(),$=t.string().describe("CSS selector, or Puppeteer selector: ::-p-xpath(...), ::-p-text(...), ::-p-aria(...), xpath/..., >>> (shadow DOM). ${VAR} placeholders are resolved."),W=t.string().describe('URL. "$VAR" as the whole value, or ${VAR} placeholders anywhere.'),L=t.enum(["load","domcontentloaded","networkidle0","networkidle2"]),M=t.enum(["left","right","middle"]),D=t.enum(["chrome","firefox"]),Z=t.strictObject({timeout:y.optional().describe("Navigation timeout in milliseconds."),waitUntil:t.union([L,L.array()]).optional().describe("When to consider the navigation finished."),referer:t.string().optional().describe("Referer header. ${VAR} placeholders are resolved.")}).optional(),H=t.strictObject({button:M.optional(),clickCount:v.optional().describe("2 for a double-click."),delay:y.optional().describe("Milliseconds between mousedown and mouseup.")}).optional(),K=t.strictObject({delay:y.optional().describe("Milliseconds between keystrokes.")}).optional(),q=t.strictObject({visible:t.boolean().optional(),hidden:t.boolean().optional(),timeout:y.optional().describe("Timeout in milliseconds.")}).optional(),Q=t.strictObject({type:t.enum(["png","jpeg"]).optional(),quality:t.number().int().min(0).max(100).optional().describe("JPEG quality (0-100)."),fullPage:t.boolean().optional(),clip:t.strictObject({x:t.number(),y:t.number(),width:t.number().positive(),height:t.number().positive()}).optional(),omitBackground:t.boolean().optional(),encoding:t.enum(["base64","binary"]).optional()}).optional(),J=t.strictObject({type:t.literal("GOTO"),url:W,options:Z}).describe("Navigate to a URL, with navigation options."),X=t.strictObject({type:t.literal("CLICK"),selector:$,options:H}).describe("Click on an element."),Y=t.strictObject({type:t.literal("TYPE"),selector:$,text:t.string().describe("Text to type. ${VAR} placeholders are resolved (keep credentials in environment variables). Never logged."),options:K}).describe("Type text into an element."),ee=t.strictObject({type:t.literal("WAIT_FOR_SELECTOR"),selector:$,options:q}).describe("Wait for an element to appear (or to be visible / hidden)."),te=t.strictObject({type:t.literal("WAIT_FOR_TIMEOUT"),timeout:y.describe("Milliseconds.")}).describe("Wait for a duration in milliseconds."),oe=t.strictObject({type:t.literal("WAIT"),milliseconds:y}).describe("Wait for a duration in milliseconds."),re=t.strictObject({type:t.literal("PAUSE")}).describe("Wait for Enter in an interactive terminal (debugging). Ignored with a warning when there is none."),ie=t.strictObject({type:t.literal("SCREENSHOT"),path:t.string().describe('File path. "$VAR" as the whole value, or ${VAR} placeholders anywhere.'),options:Q}).describe("Take a screenshot."),ne=t.strictObject({type:t.literal("EVALUATE"),script:t.string().describe("JavaScript evaluated in the page. Never interpolated.")}).describe("Evaluate JavaScript in the page."),se=t.strictObject({type:t.literal("SET_VIEWPORT"),width:v,height:v}).describe("Set the page viewport size."),ae=t.strictObject({type:t.literal("CLOSE")}).describe("Close the page."),P=t.discriminatedUnion("type",[J,X,Y,ee,te,oe,re,ie,ne,se,ae]),ce=t.strictObject({navigate:W}).describe('Navigate to a URL ("$VAR[workerIndex]" gives one URL per worker).'),pe=t.literal("waitForever").describe("Keep the page open forever."),le=t.strictObject({wait:t.number().nonnegative().describe("Seconds.")}).describe("Wait for a duration in seconds."),ue=t.strictObject({click:$}).describe("Click on an element."),de=t.strictObject({input:t.strictObject({selector:$,text:t.string().describe("Text to type. ${VAR} placeholders are resolved (keep credentials in environment variables). Never logged.")})}).describe("Type text into an element."),ge=t.union([ce,pe,le,ue,de,P]),he=t.strictObject({name:t.string().optional().describe('Scenario name (default: "Scenario <n>").'),browser:D.optional().describe("Browser to use (default: chrome)."),run:t.enum(["PARALLEL","SEQUENTIAL"]).optional().describe("Worker start strategy (default: PARALLEL). PARALLEL: all workers start after initialDelaySeconds. SEQUENTIAL: worker n starts after n \xD7 initialDelaySeconds."),initialDelaySeconds:t.number().nonnegative().optional().describe("Start delay, applied once per worker before its first iteration (see run)."),workers:v.optional().describe("Number of parallel workers (default: 1)."),iterations:v.optional().describe("Repetitions per worker (default: 1)."),location:W.optional().describe('Starting URL. "$VAR", ${VAR} placeholders, or "$VAR[workerIndex]" for one URL per worker.'),steps:t.array(ge).optional().describe("Shorthand steps; full actions are accepted too, to mix both syntaxes in order."),actions:t.array(P).optional().describe("Full actions, run after steps.")}).describe("A population of users: its workers run the steps and actions for the given number of iterations."),B=t.strictObject({scenarios:t.array(he).describe("Scenarios, all started at the same time.")});var V=r=>r instanceof Error?r.message:String(r),b=class extends Error{constructor(e,o){super(e,o),this.name="ConfigurationError"}},T=class extends Error{scenarioName;workerIndex;iteration;constructor(e,o,i,n){super(`Scenario "${e}" (worker ${o}, iteration ${i}) failed: ${V(n)}`,{cause:n}),this.name="WorkerError",this.scenarioName=e,this.workerIndex=o,this.iteration=i}},E=class extends Error{browser;constructor(e,o){super(`Failed to launch browser "${e}": ${V(o)}`,{cause:o}),this.name="BrowserLaunchError",this.browser=e}};var I=r=>{let e;try{e=F.load(r)}catch(i){throw new b(`Invalid YAML syntax: ${i instanceof Error?i.message:String(i)}`,{cause:i})}let o=B.safeParse(e);if(!o.success)throw new b(`Invalid scenario configuration:
+${_.prettifyError(o.error)}`,{cause:o.error});return o.data};var f={debug(r){console.log(r)},info(r){console.log(r)},warn(r){console.log(r)},error(r){console.error(r)}};var we=/^[A-Za-z_][A-Za-z0-9_]*$/,be=/^\$([A-Za-z_][A-Za-z0-9_]*)$/,Se=/^\$([A-Za-z_][A-Za-z0-9_]*)\[workerIndex\]$/,fe=/\$\$\{|\$\{([^}]*)\}/g,U='per-worker values ("$VAR[workerIndex]") are only supported as the whole value of location and navigate',O=class{envVarResolve;logger;constructor(e,o=f){this.envVarResolve=e,this.logger=o}resolve(e){return{scenarios:e.scenarios.map((o,i)=>this.resolveScenario(o,i+1))}}resolveScenario(e,o){let i={name:e.name||`Scenario ${o}`,workers:e.workers||1};this.logger.debug(`Resolving scenario "${i.name}" (${e.steps?.length??0} step(s), ${e.actions?.length??0} action(s))`);let n=[];try{e.location&&n.push(this.createNavigateAction(e.location,i));for(let s of e.steps??[])n.push(this.resolveStep(s,i));for(let s of e.actions??[])n.push(this.resolveAction(s))}catch(s){throw new b(`Scenario "${i.name}": ${s instanceof Error?s.message:String(s)}`,{cause:s})}let a=e.run==="SEQUENTIAL"?{delaySecondsBetweenWorkerInits:e.initialDelaySeconds||0}:{initialDelaySeconds:e.initialDelaySeconds||0};return{name:i.name,browser:e.browser||"chrome",run:a,workers:i.workers,iterations:e.iterations||1,actions:n}}resolveStep(e,o){return e==="waitForever"?{actionType:"WaitForever"}:"type"in e?this.resolveAction(e):"wait"in e?{actionType:"Wait",milliseconds:e.wait*1e3}:"navigate"in e?this.createNavigateAction(e.navigate,o):"click"in e?{actionType:"CLICK",selector:this.interpolate(e.click)}:{actionType:"TYPE",selector:this.interpolate(e.input.selector),text:this.interpolate(e.input.text)}}resolveAction(e){switch(this.logger.debug(`Resolving action: ${e.type}`),e.type){case"GOTO":return{actionType:"GOTO",url:this.resolveWholeValueOrInterpolate(e.url),options:e.options&&{...e.options,referer:e.options.referer&&this.interpolate(e.options.referer)}};case"WAIT":return{actionType:"Wait",milliseconds:e.milliseconds};case"CLICK":return{actionType:"CLICK",selector:this.interpolate(e.selector),options:e.options};case"TYPE":return{actionType:"TYPE",selector:this.interpolate(e.selector),text:this.interpolate(e.text),options:e.options};case"WAIT_FOR_SELECTOR":return{actionType:"WAIT_FOR_SELECTOR",selector:this.interpolate(e.selector),options:e.options};case"WAIT_FOR_TIMEOUT":return{actionType:"WAIT_FOR_TIMEOUT",timeout:e.timeout};case"PAUSE":return{actionType:"PAUSE"};case"SCREENSHOT":return{actionType:"SCREENSHOT",path:this.resolveWholeValueOrInterpolate(e.path),options:e.options};case"EVALUATE":return{actionType:"EVALUATE",script:e.script};case"SET_VIEWPORT":return{actionType:"SET_VIEWPORT",width:e.width,height:e.height};case"CLOSE":return{actionType:"CLOSE"};default:return e}}createNavigateAction(e,o){let i=Se.exec(e);if(i){let n=i[1],a=this.env(n).split(",").map(s=>s.trim());if(a.some(s=>s===""))throw new Error(`environment variable "${n}" (used as "${e}") contains an empty value`);if(a.length<o.workers)throw new Error(`environment variable "${n}" (used as "${e}") provides ${a.length} value(s) for ${o.workers} worker(s)`);return{actionType:"Navigate",location:{workerIndex:a}}}return{actionType:"Navigate",location:{url:this.resolveWholeValueOrInterpolate(e)}}}resolveWholeValueOrInterpolate(e){let o=be.exec(e);if(o)return this.env(o[1]);if(/^\$[A-Za-z_]/.test(e))throw new Error(`unsupported environment variable reference "${e}": use "$VAR" for the whole value or "\${VAR}" inside a value`+(e.endsWith("[workerIndex]")?`; ${U}`:""));return this.interpolate(e)}interpolate(e){return e.replace(fe,(o,i)=>{if(o==="$${")return"${";if(i===void 0||!we.test(i))throw new Error(`invalid placeholder "${o}": expected \${VAR_NAME}`+(i?.endsWith("[workerIndex]")?`; ${U}`:""));return this.env(i)})}env(e){return this.logger.debug(`Resolving environment variable "${e}"`),this.envVarResolve(e)}};import{setTimeout as x}from"node:timers/promises";function Ae(r,e){let o=e||"png";return r.endsWith(".png")||r.endsWith(".jpeg")||r.endsWith(".jpg")||r.endsWith(".webp")?r:`${r}.${o}`}var ye=(r,e)=>"delaySecondsBetweenWorkerInits"in r?r.delaySecondsBetweenWorkerInits*e:r.initialDelaySeconds,j=async(r,e,o=f,i)=>{let n=[],a=async s=>{let p=ye(e.run,s),m="delaySecondsBetweenWorkerInits"in e.run?"SEQUENTIAL":"PARALLEL";o.info(`Scenario "${e.name}" (worker ${s}) started (${m}, starting in ${p}s).`),await x(p*1e3);for(let u=0;u<e.iterations;u++)try{await ve(r,e,s,u,o,i)}catch(S){let g=new T(e.name,s,u,S);o.error(g.message),n.push(g)}};if(await Promise.all(Array.from({length:e.workers},(s,p)=>a(p))),n.length>0){n.sort((p,m)=>p.workerIndex-m.workerIndex||p.iteration-m.iteration);let s=e.workers*e.iterations;throw new AggregateError(n,`Scenario "${e.name}": ${n.length}/${s} iteration(s) failed`)}},ve=async(r,e,o,i,n,a)=>{let s;try{s=await r.newPage(),a&&await a(s,{scenarioName:e.name,workerIndex:o,iteration:i}),await $e(e.name,e.actions,s,o,n)}finally{s&&!s.isClosed()&&await s.close().catch(p=>n.warn(`Scenario "${e.name}" (worker ${o}, iteration ${i}) > failed to close page: ${p}`))}},$e=async(r,e,o,i,n=f)=>{for(let a of e){let{actionType:s}=a;switch(s){case"Navigate":let p=a;"url"in p.location?(n.info(`Scenario "${r}" (worker ${i}) > Navigating to location "${p.location.url}"`),await o.goto(p.location.url)):(n.info(`Scenario "${r}" (worker ${i}) > Navigating to indexed location "${p.location.workerIndex[i]}"`),await o.goto(p.location.workerIndex[i]));break;case"Wait":let m=a;n.info(`Scenario "${r}" (worker ${i}) > Waiting ${m.milliseconds} milliseconds...`),await x(m.milliseconds);break;case"WaitForever":for(n.info(`Scenario "${r}" (worker ${i}) > Waiting forever...`);;)await x(3600*1e3);break;case"GOTO":let u=a;n.info(`Scenario "${r}" (worker ${i}) > GOTO "${u.url}"`);let S={timeout:u.options?.timeout,waitUntil:u.options?.waitUntil,referer:u.options?.referer};await o.goto(u.url,S);break;case"CLICK":let g=a;n.info(`Scenario "${r}" (worker ${i}) > CLICK on "${g.selector}"`);let C={button:g.options?.button,clickCount:g.options?.clickCount,delay:g.options?.delay};await o.click(g.selector,C);break;case"TYPE":let w=a;n.info(`Scenario "${r}" (worker ${i}) > TYPE into "${w.selector}"`),await o.type(w.selector,w.text,w.options);break;case"WAIT_FOR_SELECTOR":let c=a;n.info(`Scenario "${r}" (worker ${i}) > WAIT_FOR_SELECTOR "${c.selector}"`),await o.waitForSelector(c.selector,c.options);break;case"WAIT_FOR_TIMEOUT":let d=a;n.info(`Scenario "${r}" (worker ${i}) > WAIT_FOR_TIMEOUT ${d.timeout} milliseconds`),await x(d.timeout);break;case"PAUSE":if(!process.stdin.isTTY){n.warn(`Scenario "${r}" (worker ${i}) > PAUSE ignored: no interactive terminal`);break}n.info(`Scenario "${r}" (worker ${i}) > PAUSE, press Enter to continue...`),await new Promise(A=>{process.stdin.resume(),process.stdin.once("data",()=>{process.stdin.pause(),A()})});break;case"SCREENSHOT":let l=a;n.info(`Scenario "${r}" (worker ${i}) > SCREENSHOT "${l.path}"`);let R={path:Ae(l.path,l.options?.type),type:l.options?.type,quality:l.options?.quality,fullPage:l.options?.fullPage,clip:l.options?.clip,omitBackground:l.options?.omitBackground,encoding:l.options?.encoding};await o.screenshot(R);break;case"EVALUATE":let k=a;n.info(`Scenario "${r}" (worker ${i}) > EVALUATE script`),await o.evaluate(k.script);break;case"SET_VIEWPORT":let h=a;n.info(`Scenario "${r}" (worker ${i}) > SET_VIEWPORT width=${h.width}, height=${h.height}`),await o.setViewport({width:h.width,height:h.height});break;case"CLOSE":n.info(`Scenario "${r}" (worker ${i}) > CLOSE page`),await o.close();break;default:throw new Error(`Unhandled action type "${s}" while evaluating scenario "${r}" on worker ${i}`)}}};import*as N from"puppeteer";var Te=(r,e)=>{if(r==="firefox")return[];let o=["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage","--disable-accelerated-2d-canvas","--disable-gpu","--ignore-certificate-errors"];return e||o.push("--start-maximized"),o},Ee=(r,e,o={})=>({browser:r,headless:e,acceptInsecureCerts:!0,...o,args:[...Te(r,e),...o.args??[]]}),G=(r,e,o)=>N.launch(Ee(r,e,o));var bt=async(r,e={})=>{let{browsers:o={},logger:i=f,onPage:n,headless:a=!0,launchOptions:s={}}=e,p=I(r),u=new O(c=>{let d=process.env[c];if(d)return d;throw new Error(`environment variable "${c}" is not set (or empty)`)},i).resolve(p),S=new Map;for(let c of u.scenarios){let d=S.get(c.browser)??[];d.push(c),S.set(c.browser,d)}let g=async(c,d)=>{let l=o[c],R=!l;if(!l)try{i.info(`Launching ${c} (headless: ${a})`),l=await G(c,a,s[c])}catch(h){let A=new E(c,h);return i.error(A.message),[A]}let k=l;try{return(await Promise.all(d.map(async A=>{try{return await j(k,A,i,n),[]}catch(z){return z instanceof AggregateError?z.errors:[z]}}))).flat()}finally{R&&await k.close().catch(h=>i.warn(`Failed to close ${c}: ${h}`))}},w=(await Promise.all([...S].map(([c,d])=>g(c,d)))).flat();if(w.length>0)throw new AggregateError(w,`${w.length} error(s) occurred while running scenarios`)};export{E as BrowserLaunchError,b as ConfigurationError,T as WorkerError,bt as readYamlAndInterpret};

package/dist/puppet/interpreter.d.ts

@@ -1,4 +1,10 @@
 import * as p from 'puppeteer';
-import { YpLogger } from '../core/logger';
-import { OnPageCallback, Scenario } from '../core/model';
-export declare const evalScenario: (browser: p.Browser, scenario: Scenario, logger?: YpLogger, onPage?: OnPageCallback) => Promise<void[]>;
+import { YpLogger } from '../core/logger.js';
+import { OnPageCallback, Scenario } from '../core/model.js';
+/**
+ * Runs every worker of the scenario, each one running all its iterations.
+ * A failing iteration interrupts neither the next iterations of the worker
+ * nor the other workers. Once everything is done, the promise rejects with an
+ * `AggregateError` of `WorkerError` (one per failed iteration) if anything failed.
+ */
+export declare const evalScenario: (browser: p.Browser, scenario: Scenario, logger?: YpLogger, onPage?: OnPageCallback) => Promise<void>;

package/dist/puppet/launcher.d.ts

@@ -0,0 +1,9 @@
+import * as p from 'puppeteer';
+import { SupportedBrowser } from '../core/model.js';
+/**
+ * Builds Puppeteer launch options for the given browser. The browser is
+ * selected with `browser` (not `channel`, which only accepts Chrome release
+ * channels). User options override defaults; user `args` are appended.
+ */
+export declare const buildLaunchOptions: (browser: SupportedBrowser, headless: boolean, extra?: p.LaunchOptions) => p.LaunchOptions;
+export declare const launchBrowser: (browser: SupportedBrowser, headless: boolean, extra?: p.LaunchOptions) => Promise<p.Browser>;