@epinova/opticli 0.27.0-preview → 0.28.0

package/README.md

@@ -4,16 +4,14 @@ Typed access to [opticli](https://github.com/epinova/opticli) from Node.js, and
 an Optimizely CMS 12 or 13 site, seed the content the tests need, give each test content of its own, and clean up
 after. Writes go through the CMS (versions, cache, events), so a page shows a change at once.
 
-**Preview.** The API may still change: install it with the `preview` tag. Its version is the opticli version it was
-released with, plus `-preview`.
-
 ## Install
 
 ```bash
-npm install -D @epinova/opticli@preview
+npm install -D @epinova/opticli
 ```
 
-The package runs the opticli CLI; it doesn't install it. It needs the opticli it was released with, or newer: pin it in
+The package runs the opticli CLI; it doesn't install it. Its version is the opticli version it was released with, and it
+needs that opticli or newer: pin it in
 the site's repository with a [local tool manifest](https://learn.microsoft.com/dotnet/core/tools/local-tools-how-to-use),
 so CI gets the same version:
 
@@ -120,7 +118,7 @@ content stays for the next run.
 | Fixture | Scope | |
 |---|---|---|
 | `seed` | worker | `refs` and `urls` (host-relative) of the plan's steps, by `id`; `baseURL`. |
-| `cms` | test | Writes undone after the test: `page(type, name, properties?, { parent?, publish? })` (published by default; returns `ref`, `version` and `url`), `set`, `publish`, `apply`. What it creates goes to the recycle bin after the test; changes to seeded content are repaired by the next run's seed. |
+| `cms` | test | Content for one test: `page(type, name, properties?, { parent?, publish?, keep? })` (published by default; returns `ref`, `version` and `url`), `set`, `publish`, `apply(plan, { keep?, ... })`. What `page` and `apply` create goes to the recycle bin after the test, unless `keep`. |
 | `sandbox` | worker | With the `opticliSandbox` option: the ref of the worker's own page, where `cms.page()` creates content. It goes to the recycle bin when the worker ends, with anything a failed test left. |
 | `opticli` | worker | The `OptiCli` client, for anything else. |
 | `baseURL` | test | The site `opticli serve` runs. |
@@ -128,6 +126,20 @@ content stays for the next run.
 `opticliSandbox`: `parent` (a ref, or `$id` of a seed step), `type` (a page type the parent allows and that allows your
 test pages), `properties`. Without it, pass `{ parent }` to `cms.page()`.
 
+### What stays, and what goes
+
+| | After the test run |
+|---|---|
+| The seed plan | Stays. The next run repairs what changed. |
+| `cms.page()`, `cms.apply()` | Go after the test. With `keep: true`, stay. |
+| `cms.set()`, `cms.publish()` | Stay: they change content the test didn't make. On seeded content the next run's seed puts it back, but tests in other workers of the same run see the change. |
+| The sandbox | Goes when the worker ends, with everything below it, whatever made it. |
+| The `opticli` fixture, the Node.js client | Stay: they never remove anything (except below the sandbox, as above). |
+
+`keep: true` needs a parent outside the sandbox and outside content the test made, since that goes with everything
+below it; `cms` refuses it there before saving anything. A step of `cms.apply()` that found its content already there
+(`updateExisting`) leaves it, with or without `keep`.
+
 Deleted content goes to the recycle bin, as in the CMS: nothing is deleted for good. On a local database that is
 usually fine; empty the recycle bin in the CMS now and then.
 
@@ -147,6 +159,7 @@ try {
 }
 ```
 
+The client changes what you tell it to and removes nothing on its own, so it suits scripts that make content to keep.
 Typed methods: `serve`, `serveStatus`, `serveStop`, `get`, `url`, `create`, `set`, `publish`, `delete`, `apply`.
 `run(args)` runs any other command and returns its JSON envelope. A failure throws `OptiCliError` with opticli's `code`,
 `exitCode`, `hint`, `details` and `version`; see opticli's
@@ -160,7 +173,7 @@ changes in one call.
 | | |
 |---|---|
 | `command` option or `OPTICLI` | The opticli to run: an executable, or a checkout's `opticli.dll` (run with `dotnet`). Otherwise `dotnet tool run opticli` when a tool manifest above the working directory has it, else `opticli` on PATH. |
-| `project` option or `OPTICLI_PROJECT` | The site's `.csproj` or folder. Otherwise opticli finds it from the working directory. |
+| `project` option or `OPTICLI_PROJECT` | The site's `.csproj` or folder, relative to `cwd` (default: the working directory). Otherwise opticli finds it from the working directory. |
 
 `apply` runs in `baseDir` (`planDir` in setup), so a tool manifest must be in or above that folder too.
 

package/lib/opticli.d.ts

@@ -6,7 +6,10 @@ export interface OptiCliOptions {
      * working directory has opticli, else `opticli` on PATH.
      */
     command?: readonly string[];
-    /** The site's project (`--project`): its `.csproj` or folder. Default: `$OPTICLI_PROJECT`, else opticli's discovery from the working directory. */
+    /**
+     * The site's project (`--project`): its `.csproj` or folder, relative to `cwd`. Default: `$OPTICLI_PROJECT`, else
+     * opticli's discovery from the working directory.
+     */
     project?: string;
     /** Working directory for every call (except `apply`'s `baseDir`). Default: the process's. */
     cwd?: string;

package/lib/opticli.js

@@ -32,7 +32,9 @@ export class OptiCli {
     constructor(options = {}) {
         this.cwd = options.cwd;
         this.command = options.command ?? resolveCommand(options.cwd ?? process.cwd());
-        this.project = options.project ?? (process.env.OPTICLI_PROJECT || undefined);
+        // Absolute: opticli resolves --project against its working directory, and apply runs in the plan's folder.
+        const project = options.project ?? (process.env.OPTICLI_PROJECT || undefined);
+        this.project = project ? resolve(options.cwd ?? process.cwd(), project) : undefined;
         this.onWarnings = options.onWarnings;
     }
     /** Runs any opticli command with `--json` and returns its envelope; throws OptiCliError when `ok` is false. */
@@ -138,20 +140,32 @@ export class OptiCli {
     }
     exec(args, options) {
         const [program, ...prefix] = this.command;
+        const timeoutMs = options.timeoutMs ?? 120_000;
         return new Promise((resolvePromise, reject) => {
-            const child = spawn(program, [...prefix, ...args], {
-                cwd: options.cwd ?? this.cwd,
-                stdio: ['pipe', 'pipe', 'pipe'],
-                timeout: options.timeoutMs ?? 120_000,
-            });
+            // The timer is ours, not spawn's `timeout`: spawn's outlives a program that never started, and keeps Node running.
+            let timer;
+            let settled = false;
+            const settle = (done) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                done();
+            };
+            const child = spawn(program, [...prefix, ...args], { cwd: options.cwd ?? this.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+            timer = setTimeout(() => {
+                child.kill();
+                const message = `no answer within ${timeoutMs / 1000} s; it was stopped`;
+                settle(() => reject(new OptiCliError({ code: 'timeout', message, hint: 'For a command that takes longer, pass a longer timeoutMs to run().' }, null, args)));
+            }, timeoutMs);
             let stdout = '';
             let stderr = '';
             child.stdout.setEncoding('utf8').on('data', (chunk) => (stdout += chunk));
             child.stderr.setEncoding('utf8').on('data', (chunk) => (stderr += chunk));
-            child.on('error', (error) => reject(error.code === 'ENOENT'
+            child.on('error', (error) => settle(() => reject(error.code === 'ENOENT'
                 ? new Error(`Couldn't run ${this.command.join(' ')}: install opticli (dotnet tool install -g OptiCli), or set OPTICLI to it.`, { cause: error })
-                : error));
-            child.on('close', (exitCode) => resolvePromise({ stdout, stderr, exitCode }));
+                : error)));
+            child.on('close', (exitCode) => settle(() => resolvePromise({ stdout, stderr, exitCode })));
             child.stdin.on('error', () => { }); // a CLI that exits before reading stdin
             child.stdin.end(options.input ?? '');
         });

package/lib/playwright/fixtures.d.ts

@@ -18,7 +18,15 @@ export interface CreatedPage extends WriteResult {
     /** The page's URL (host-relative), for `page.goto`; for a draft, where it will be once published. */
     url: string;
 }
-/** Writes that a test's content gets, undone after the test. */
+/** Leave the content on the site after the test: `cms.page(..., { keep: true, parent })`. */
+export interface KeepOption {
+    /**
+     * Don't remove what this call creates after the test. It needs a parent outside the worker's sandbox and outside
+     * content the test made, which both go after the test (or worker) with everything below them.
+     */
+    keep?: boolean;
+}
+/** Writes that a test's content gets, undone after the test unless `keep`. */
 export declare class Cms {
     readonly opticli: OptiCli;
     /** Where {@link page} creates content unless given a parent: the worker's sandbox. */
@@ -27,19 +35,24 @@ export declare class Cms {
     constructor(opticli: OptiCli, 
     /** Where {@link page} creates content unless given a parent: the worker's sandbox. */
     parent: ContentRef | undefined);
-    /** Creates a page, published unless `publish: false`, and removes it after the test. */
-    page(type: string, name: string, properties?: Properties, options?: WriteOptions & {
+    /** Creates a page, published unless `publish: false`, and removes it after the test unless `keep`. */
+    page(type: string, name: string, properties?: Properties, { parent: given, keep, ...options }?: WriteOptions & KeepOption & {
         parent?: ContentRef;
     }): Promise<CreatedPage>;
     /** Saves a draft of the change unless `publish`. On seeded content, the next run's seed puts it back. */
     set(ref: ContentRef, properties: Properties, options?: WriteOptions): Promise<WriteResult>;
     /** Publishes the latest version, or the version `ref` names (`123_456`). */
     publish(ref: ContentRef): Promise<WriteResult>;
-    /** Runs a plan; what it creates below existing content is removed after the test. */
-    apply(plan: Plan, options?: Parameters<OptiCli['apply']>[1]): Promise<ApplyResult>;
+    /**
+     * Runs a plan; what it creates is removed after the test unless `keep`. Content that was there before (a step
+     * that found it with `updateExisting`) stays.
+     */
+    apply(plan: Plan, { keep, ...options }?: Parameters<OptiCli['apply']>[1] & KeepOption): Promise<ApplyResult>;
     /** Deletes what the test made, newest first. Content below other tracked content goes with it. */
     cleanup(): Promise<void>;
     private track;
+    /** Refuses `keep` below content that goes after the test or worker, before anything is saved. */
+    private checkKeep;
 }
 type TestFixtures = {
     cms: Cms;

package/lib/playwright/fixtures.js

@@ -8,7 +8,7 @@
 import { test as base } from '@playwright/test';
 import { OptiCli, OptiCliError } from "../opticli.js";
 import { readSeedState } from "./setup.js";
-/** Writes that a test's content gets, undone after the test. */
+/** Writes that a test's content gets, undone after the test unless `keep`. */
 export class Cms {
     opticli;
     parent;
@@ -19,13 +19,16 @@ export class Cms {
         this.opticli = opticli;
         this.parent = parent;
     }
-    /** Creates a page, published unless `publish: false`, and removes it after the test. */
-    async page(type, name, properties = {}, options = {}) {
-        const parent = options.parent ?? this.parent;
+    /** Creates a page, published unless `publish: false`, and removes it after the test unless `keep`. */
+    async page(type, name, properties = {}, { parent: given, keep, ...options } = {}) {
+        const parent = given ?? this.parent;
         if (!parent)
             throw new Error('cms.page() needs a parent: pass { parent }, or set the opticliSandbox option in playwright.config.');
+        if (keep)
+            this.checkKeep('cms.page()', [parent]);
         const result = await this.opticli.create(parent, type, name, properties, { ...options, publish: options.publish ?? true });
-        this.track(result.ref, parent);
+        if (!keep)
+            this.track(result.ref, parent);
         if (!result.url)
             throw new Error(`${type} ${result.ref} has no URL: is ${type} a page type with a template?`);
         return result;
@@ -38,12 +41,22 @@ export class Cms {
     publish(ref) {
         return this.opticli.publish(ref);
     }
-    /** Runs a plan; what it creates below existing content is removed after the test. */
-    async apply(plan, options = {}) {
+    /**
+     * Runs a plan; what it creates is removed after the test unless `keep`. Content that was there before (a step
+     * that found it with `updateExisting`) stays.
+     */
+    async apply(plan, { keep, ...options } = {}) {
+        if (keep) {
+            const parents = plan.operations.map((step) => (isCreate(step) ? (step.parent ?? step.for) : undefined));
+            this.checkKeep('cms.apply()', parents.filter((p) => p !== undefined));
+        }
         const result = await this.opticli.apply(plan, options);
-        for (const step of plan.operations) {
-            if ((step.op === 'create' || step.op === 'block' || step.op === 'upload') && step.id && result.created[step.id]) {
-                this.track(result.created[step.id], step.parent ?? step.for);
+        if (keep)
+            return result;
+        for (const step of result.operations) {
+            const planned = plan.operations[step.index];
+            if (step.id && result.created[step.id] && isCreate(planned) && !step.result?.existing) {
+                this.track(result.created[step.id], planned.parent ?? planned.for);
             }
         }
         return result;
@@ -70,6 +83,20 @@ export class Cms {
             return;
         this.created.push(ref);
     }
+    /** Refuses `keep` below content that goes after the test or worker, before anything is saved. */
+    checkKeep(call, parents) {
+        for (const parent of parents) {
+            if (parent === this.parent) {
+                throw new Error(`${call} with keep: true needs a parent outside the worker's sandbox, which goes when the worker ends.`);
+            }
+            if (this.created.includes(parent)) {
+                throw new Error(`${call} with keep: true can't go below ${parent}, which this test made and which goes after it.`);
+            }
+        }
+    }
+}
+function isCreate(step) {
+    return step?.op === 'create' || step?.op === 'block' || step?.op === 'upload';
 }
 /**
  * The fixtures, with `seed.refs` and `seed.urls` typed by the seed plan's step ids:

package/lib/playwright/index.d.ts

@@ -1,5 +1,5 @@
 export { Cms, createTest } from './fixtures.ts';
-export type { CreatedPage, OptiCliWorkerOptions, SandboxOptions } from './fixtures.ts';
+export type { CreatedPage, KeepOption, OptiCliWorkerOptions, SandboxOptions } from './fixtures.ts';
 export { defineSetup, readSeedState, stateVariable } from './setup.ts';
 export type { SeedState, SetupOptions } from './setup.ts';
 export { OptiCliError } from '../opticli.ts';

package/lib/playwright/setup.d.ts

@@ -12,7 +12,7 @@ export interface SetupOptions {
     publish?: boolean;
     /** Build the site before starting it (`serve --build`). Default: `OPTICLI_BUILD=1`. */
     build?: boolean;
-    /** Leave a site that setup started running after the tests. Default: `OPTICLI_KEEP_SITE=1`. */
+    /** Leave a site that setup started running after the tests, or after setup failed. Default: `OPTICLI_KEEP_SITE=1`. */
     keepSite?: boolean;
     /** How to run opticli, and which project. */
     opticli?: Pick<OptiCliOptions, 'command' | 'project' | 'cwd'>;

package/lib/playwright/setup.js

@@ -22,39 +22,51 @@ export function defineSetup(options = {}) {
             onWarnings: (warnings, args) => console.warn(`opticli ${args[0]}: ${warnings.join(' ')}`),
         });
         const before = await opticli.serveStatus();
-        const served = await opticli.serve({ build: options.build ?? process.env.OPTICLI_BUILD === '1' });
-        checkVersions(served.meta.version, served.data.agent?.version);
-        const baseURL = served.data.browseUrl ?? served.data.url;
-        if (!baseURL)
-            throw new Error(`opticli serve gave no URL: ${JSON.stringify(served.data)}`);
-        const state = {
-            baseURL,
-            opticli: { command: opticli.command, project: opticli.project, cwd: opticli.cwd },
-            refs: {},
-            urls: {},
-        };
-        if (options.plan) {
-            const applied = await opticli.apply(options.plan, {
-                baseDir: options.planDir,
-                updateExisting: true,
-                publish: options.publish ?? true,
-            });
-            state.refs = applied.created;
-            for (const step of applied.operations) {
-                if (step.id && step.result?.url)
-                    state.urls[step.id] = step.result.url;
-            }
-            const changed = applied.operations.filter((o) => o.status !== 'unchanged').length;
-            console.log(`opticli: seed plan ${changed ? `changed ${changed} of ${applied.operations.length} steps` : 'unchanged'}`);
-        }
-        process.env[stateVariable] = JSON.stringify(state);
         const startedSite = before.state !== 'running';
-        return async () => {
-            if (startedSite && !(options.keepSite ?? process.env.OPTICLI_KEEP_SITE === '1'))
+        const keepSite = options.keepSite ?? process.env.OPTICLI_KEEP_SITE === '1';
+        const teardown = async () => {
+            if (startedSite && !keepSite)
                 await opticli.serveStop();
         };
+        const served = await opticli.serve({ build: options.build ?? process.env.OPTICLI_BUILD === '1' });
+        try {
+            process.env[stateVariable] = JSON.stringify(await seed(opticli, served, options));
+        }
+        catch (error) {
+            // Playwright runs no teardown when setup fails: stop the site setup started here.
+            await teardown().catch((stopError) => console.warn(`opticli: couldn't stop the site: ${stopError}`));
+            throw error;
+        }
+        return teardown;
     };
 }
+async function seed(opticli, served, options) {
+    checkVersions(served.meta.version, served.data.agent?.version);
+    const baseURL = served.data.browseUrl ?? served.data.url;
+    if (!baseURL)
+        throw new Error(`opticli serve gave no URL: ${JSON.stringify(served.data)}`);
+    const state = {
+        baseURL,
+        opticli: { command: opticli.command, project: opticli.project, cwd: opticli.cwd },
+        refs: {},
+        urls: {},
+    };
+    if (options.plan) {
+        const applied = await opticli.apply(options.plan, {
+            baseDir: options.planDir,
+            updateExisting: true,
+            publish: options.publish ?? true,
+        });
+        state.refs = applied.created;
+        for (const step of applied.operations) {
+            if (step.id && step.result?.url)
+                state.urls[step.id] = step.result.url;
+        }
+        const changed = applied.operations.filter((o) => o.status !== 'unchanged').length;
+        console.log(`opticli: seed plan ${changed ? `changed ${changed} of ${applied.operations.length} steps` : 'unchanged'}`);
+    }
+    return state;
+}
 /** The workers' copy of what setup did. */
 export function readSeedState() {
     const json = process.env[stateVariable];

package/lib/version.d.ts

@@ -1,4 +1,4 @@
-/** This package's version, which build.mjs sets: opticli's version, with `-preview` while the API may still change. */
+/** This package's version, which build.mjs sets: opticli's version. */
 export declare const version = "0.0.0-dev";
 /** The oldest opticli this package works with: the one released with it. */
 export declare const requiredOpticli: string;

package/lib/version.js

@@ -1,4 +1,4 @@
-/** This package's version, which build.mjs sets: opticli's version, with `-preview` while the API may still change. */
-export const version = '0.27.0-preview';
+/** This package's version, which build.mjs sets: opticli's version. */
+export const version = '0.28.0';
 /** The oldest opticli this package works with: the one released with it. */
 export const requiredOpticli = version.split('-')[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epinova/opticli",
-  "version": "0.27.0-preview",
+  "version": "0.28.0",
   "description": "Typed Node API and Playwright fixtures for opticli: start an Optimizely CMS site, seed test content and clean up after the tests",
   "license": "MPL-2.0",
   "type": "module",