@leera.io/qa-runner 1.2.0 → 1.4.0

package/dist/src/drivers/windows-appium.js

@@ -9,12 +9,41 @@ import { clip, errorMessage, expectWithin, matches, renderLaunchArgs } from './c
 import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
 import { Blocked, LaunchRefused, } from './driver.js';
 import { emptyScreen } from './snapshot/format.js';
-import { windowsKeyActions } from './webdriver/desktop-keys.js';
+import { windowsKeyActions, windowsOpenDialogEntries } from './webdriver/desktop-keys.js';
 import { elementIdOf } from './webdriver/locate.js';
 import { NATIVE_DESKTOP_ACTIONS } from './webdriver/native-actions.js';
-import { describeWindowsTarget, WINDOWS_LOCATORS, windowsSelectors, xpathLiteral } from './webdriver/native-locate.js';
+import { describeWindowsTarget, nativeLocate, WINDOWS_LOCATORS, windowsSelectors, xpathLiteral } from './webdriver/native-locate.js';
 import { openSession, webdriverMessage } from './webdriver/session.js';
 import { windowsSnapshotFromXml } from './webdriver/xml-tree-desktop.js';
+/** The AutomationId of the File name box of the common Open dialog. */
+export const OPEN_DIALOG_FILE_NAME_BOX = '1148';
+/**
+ * Picks files in the common Open dialog: each entry goes into its File name box (replacing what
+ * is there) followed by Enter; the dialog must be gone afterwards, or it refused the files.
+ */
+export async function fillWindowsOpenDialog(client, folder, names, timeoutMs, pauseMs = 500) {
+    const box = await nativeLocate(client, windowsSelectors, { automation_id: OPEN_DIALOG_FILE_NAME_BOX }, timeoutMs);
+    if (!box) {
+        throw new Error('no Open dialog appeared after the click (its File name box was not found); target the control that opens the dialog');
+    }
+    const selectAll = windowsKeyActions({ modifiers: ['ctrl'], key: 'a' });
+    const enter = windowsKeyActions({ modifiers: [], key: 'enter' });
+    for (const entry of windowsOpenDialogEntries(folder, names)) {
+        await client.elementClick(box.elementId).catch(() => undefined);
+        await windowsCommand(client, 'keys', { actions: [...selectAll, { text: entry }, ...enter] });
+        await sleep(pauseMs);
+    }
+    const deadline = Date.now() + Math.max(timeoutMs, 1_000);
+    for (;;) {
+        const open = await client.isElementDisplayed(box.elementId).catch(() => false);
+        if (!open)
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`the Open dialog did not accept the files (${names.join(', ')}); it is still open`);
+        }
+        await sleep(300);
+    }
+}
 /** Runs an Appium Windows driver `windows:` extension command. */
 export function windowsCommand(client, command, args = {}) {
     if (!/^[a-zA-Z]+$/.test(command))
@@ -106,7 +135,7 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
     wadUrl = null;
     disposed = false;
     constructor(ctx, appium, deps = {}) {
-        super(ctx, appium);
+        super(ctx, appium, deps.recorder);
         this.deps = deps;
     }
     get ops() {
@@ -193,6 +222,9 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
                 case 'focus_window':
                     await this.focusWindow(action);
                     return {};
+                case 'upload':
+                    await this.upload(action);
+                    return {};
                 default:
                     return await this.runShared(action);
             }
@@ -201,6 +233,9 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
             throw this.translate(error);
         }
     }
+    pickInOpenDialog(folder, names, timeoutMs) {
+        return fillWindowsOpenDialog(this.requireClient(), folder, names, timeoutMs);
+    }
     /**
      * Switches to the app window with that title; a window the app's session does not list (a
      * dialog of another process) is attached to through a desktop session and `appTopLevelWindow`.

package/dist/src/executor.js

@@ -1,5 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import { describe, errorMessage, firstLine, screenshotName } from './drivers/common.js';
+import { mp4Seconds } from './devices/mp4.js';
 import { isPlatform } from './devices/types.js';
 import { Blocked, LaunchRefused } from './drivers/driver.js';
 import { BrowserPool, webPlaywrightFactory } from './drivers/web-playwright.js';
@@ -37,12 +38,15 @@ export function jobPlatform(job) {
     return platform;
 }
 export function jobContext(job, options) {
+    const template = templateContextFor(job);
+    if (options.files)
+        template.files = options.files.files;
     return {
         jobId: job.job.id,
         platform: jobPlatform(job),
         lease: options.lease,
         job,
-        template: templateContextFor(job),
+        template,
         timeouts: { actionMs: options.actionTimeoutMs, jobMs: options.jobTimeoutMs },
         headless: options.headless,
         ...(options.proxy ? { proxy: options.proxy } : {}),
@@ -51,6 +55,7 @@ export function jobContext(job, options) {
         log: options.log,
         ...(options.app ?? {}),
         ...(options.buildDownloadUrl ? { buildDownloadUrl: options.buildDownloadUrl } : {}),
+        ...(options.files ? { files: options.files } : {}),
     };
 }
 /**
@@ -179,6 +184,8 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
         videoPath = await driver.stopRecording().catch(() => undefined);
         await driver.dispose().catch(() => undefined);
     }
+    if (videoPath)
+        keepOffsetsInVideo(steps, mp4Seconds(videoPath));
     return {
         steps,
         elapsedSecs: Math.max(1, Math.round((Date.now() - started) / 1000)),
@@ -186,6 +193,20 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
         ...(videoPath ? { videoPath } : {}),
     };
 }
+/**
+ * Places no step past the end of the video (`seconds` long, null when unknown): a video can end a
+ * moment before a step that began just before it stopped, and that step is then shown at its end.
+ */
+export function keepOffsetsInVideo(steps, seconds) {
+    if (seconds === null)
+        return;
+    const end = Math.floor(seconds * 10) / 10;
+    for (const step of steps) {
+        const offset = step.debug?.video_offset_secs;
+        if (offset !== undefined && offset > end)
+            step.debug = { ...step.debug, video_offset_secs: end };
+    }
+}
 /** Prefixes the action's description; template problems block the step rather than fail it. */
 async function runAction(driver, action) {
     try {

package/dist/src/files/store.js

@@ -0,0 +1,181 @@
+import { randomFillSync } from 'node:crypto';
+import { closeSync, constants, copyFileSync, linkSync, mkdirSync, mkdtempSync, openSync, rmSync, statSync, truncateSync, writeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { BuildCache } from '../builds/cache.js';
+import { obtainBuild } from '../builds/download.js';
+/** The largest generated file the runner writes: the server's own limit. */
+export const MAX_GENERATED_BYTES = 2 * 1024 * 1024 * 1024;
+/** Test files stay small; 2 GB of them are kept between jobs by default. */
+export const DEFAULT_FILE_CACHE_BYTES = 2 * 1024 * 1024 * 1024;
+const WRITE_CHUNK = 1024 * 1024;
+export class TestFileError extends Error {
+}
+/** `~/.leera-qa-runner/cache/test-files`. */
+export function testFileCacheDir(paths) {
+    return join(paths.root, 'cache', 'test-files');
+}
+const caches = new Map();
+/** One cache object per directory per process, so pins are shared between jobs. */
+export function testFileCacheFor(paths, maxBytes = DEFAULT_FILE_CACHE_BYTES) {
+    const dir = testFileCacheDir(paths);
+    let cache = caches.get(dir);
+    if (!cache) {
+        cache = new BuildCache(dir, maxBytes);
+        caches.set(dir, cache);
+    }
+    return cache;
+}
+/**
+ * The name a file is written under: the server checked it is a plain file name every OS accepts;
+ * anything that still names a folder or a device is refused here too, so a job can never write
+ * outside its own folder.
+ */
+export function checkedFileName(fileName) {
+    const name = typeof fileName === 'string' ? fileName : '';
+    const plain = name.length > 0 && name.length <= 255 && basename(name) === name && !name.includes('\\') && !name.includes('/');
+    const control = [...name].some((ch) => ch.charCodeAt(0) < 0x20);
+    if (!plain || control || name === '.' || name === '..' || /[<>:"|?*]/.test(name)) {
+        throw new TestFileError(`the test file name '${name}' cannot be written on this runner`);
+    }
+    return name;
+}
+/**
+ * A job's test files on this machine: `<job folder>/<name>/<file name>`, so each keeps the name
+ * the app should see even when two share it. Stored files come through the digest-checked cache;
+ * generated files are written here. Disposing removes the folder.
+ */
+export class JobFiles {
+    dir;
+    files;
+    releases;
+    picks = 0;
+    constructor(dir, files, releases) {
+        this.dir = dir;
+        this.files = files;
+        this.releases = releases;
+    }
+    /** No files: a job whose script hands none over. */
+    static empty() {
+        return new JobFiles('', {}, []);
+    }
+    static async prepare(options) {
+        const entries = Object.entries(options.files ?? {});
+        if (entries.length === 0)
+            return JobFiles.empty();
+        const dir = mkdtempSync(join(options.root ?? tmpdir(), 'qa-files-'));
+        const files = {};
+        const releases = [];
+        const store = new JobFiles(dir, files, releases);
+        try {
+            for (const [name, file] of entries) {
+                if (!/^[a-z][a-z0-9_]{0,39}$/.test(name))
+                    throw new TestFileError(`'${name}' is not a test file name`);
+                const fileName = checkedFileName(file.file_name);
+                const folder = join(dir, name);
+                mkdirSync(folder, { recursive: true, mode: 0o700 });
+                const target = join(folder, fileName);
+                if (file.kind === 'generated') {
+                    writeGenerated(target, file);
+                }
+                else if (file.kind === 'stored') {
+                    const obtained = await obtainBuild({
+                        cache: options.cache,
+                        build: {
+                            id: file.id,
+                            version_name: null,
+                            build_number: null,
+                            file_name: fileName,
+                            sha256: file.sha256 ?? '',
+                            size_bytes: file.size_bytes,
+                        },
+                        getUrl: () => options.downloadUrl(file.id),
+                        what: `test file ${name}`,
+                        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+                    });
+                    releases.push(obtained.release);
+                    copyFileSync(obtained.path, target, constants.COPYFILE_FICLONE);
+                }
+                else {
+                    throw new TestFileError(`test file ${name} is of a kind this runner does not know (${file.kind}); update the runner`);
+                }
+                files[name] = { file_name: fileName, path: target };
+            }
+            options.cache.prune();
+            return store;
+        }
+        catch (error) {
+            await store.dispose();
+            throw error;
+        }
+    }
+    /**
+     * A new folder holding exactly these files under their own names, for an Open dialog that picks
+     * everything in one folder. Links where the filesystem allows, copies otherwise.
+     */
+    folderWith(paths) {
+        if (!this.dir)
+            throw new TestFileError('the job has no test files');
+        this.picks += 1;
+        const folder = join(this.dir, `.pick-${this.picks}`);
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        const seen = new Set();
+        for (const path of paths) {
+            const name = basename(path);
+            if (seen.has(name.toLowerCase())) {
+                throw new TestFileError(`two of the files are named ${name}; an Open dialog cannot pick both`);
+            }
+            seen.add(name.toLowerCase());
+            const target = join(folder, name);
+            try {
+                linkSync(path, target);
+            }
+            catch {
+                copyFileSync(path, target, constants.COPYFILE_FICLONE);
+            }
+        }
+        return folder;
+    }
+    async dispose() {
+        for (const release of this.releases.splice(0))
+            release();
+        if (this.dir)
+            rmSync(this.dir, { recursive: true, force: true });
+    }
+}
+/** Writes a generated file: zeros (sparse where the filesystem allows) or random bytes. */
+export function writeGenerated(path, file) {
+    const size = file.size_bytes;
+    if (!Number.isSafeInteger(size) || size < 0 || size > MAX_GENERATED_BYTES) {
+        throw new TestFileError(`test file ${file.name} has a size this runner will not generate (${size} bytes)`);
+    }
+    const fill = file.fill ?? 'zeros';
+    if (fill === 'zeros') {
+        const fd = openSync(path, 'w', 0o600);
+        closeSync(fd);
+        truncateSync(path, size);
+    }
+    else if (fill === 'random') {
+        const fd = openSync(path, 'w', 0o600);
+        try {
+            const chunk = Buffer.allocUnsafe(Math.min(WRITE_CHUNK, Math.max(size, 1)));
+            let left = size;
+            while (left > 0) {
+                const length = Math.min(left, chunk.length);
+                randomFillSync(chunk, 0, length);
+                let offset = 0;
+                while (offset < length)
+                    offset += writeSync(fd, chunk, offset, length - offset);
+                left -= length;
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    else {
+        throw new TestFileError(`test file ${file.name} has a fill this runner does not know (${fill}); update the runner`);
+    }
+    if (statSync(path).size !== size)
+        throw new TestFileError(`test file ${file.name} was not written in full`);
+}

package/dist/src/runner.js

@@ -1,5 +1,6 @@
 import { readFile, rm, stat } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { buildCapabilities, detect, hostInfo } from './capabilities.js';
 import { ApiError, RunnerClient } from './client.js';
 import { loadFileConfig, resolveConfig } from './config.js';
@@ -9,6 +10,7 @@ import { createRegistry, defaultFactories } from './drivers/registry.js';
 import { BrowserPool } from './drivers/web-playwright.js';
 import { ExitCode, ExitError, messageOf } from './errors.js';
 import { createDriver, executeClaimedJob, jobContext, sessionContext } from './executor.js';
+import { JobFiles, testFileCacheFor } from './files/store.js';
 import { HealthMonitor, healthReport } from './health.js';
 import { homePaths, readJsonFile, writePrivateFile } from './home.js';
 import { progressReporter } from './progress.js';
@@ -339,10 +341,18 @@ export class Runner {
             }
         });
         let videoPath;
+        let files = JobFiles.empty();
         try {
+            // Downloaded or generated before the app starts, so a step never waits on the network.
+            files = await JobFiles.prepare({
+                files: job.files,
+                cache: testFileCacheFor(this.deps.paths ?? { root: join(tmpdir(), 'leera-qa-runner') }),
+                downloadUrl: (testFileId) => client.testFileDownloadUrl(testFileId, jobId),
+            });
             const ctx = jobContext(job, {
                 lease,
                 app: this.appSettings(),
+                files,
                 buildDownloadUrl: (buildId) => client.buildDownloadUrl(buildId, { jobId }),
                 actionTimeoutMs: config.actionTimeoutMs,
                 jobTimeoutMs: config.jobTimeoutMs,
@@ -443,6 +453,7 @@ export class Runner {
             clearInterval(heartbeat);
             progress.stop();
             this.running.delete(jobId);
+            await files.dispose().catch(() => undefined);
             // Each job records into its own temporary directory.
             if (videoPath)
                 await rm(dirname(videoPath), { recursive: true, force: true }).catch(() => undefined);

package/dist/src/template.js

@@ -38,6 +38,8 @@ export function redactDeep(value, redact) {
 function placeholderValue(name, ctx) {
     if (name.startsWith('data.'))
         return dataValue(name, ctx);
+    if (name.startsWith('file.'))
+        return testFile(name.slice('file.'.length), name, ctx).file_name;
     switch (name) {
         case 'env.base_url':
             return trimSlash(ctx.baseUrl);
@@ -107,6 +109,43 @@ function dataValue(name, ctx) {
     }
     return value;
 }
+/** A test file of the job by name; `placeholder` is how the script wrote it, for messages. */
+export function testFile(fileName, placeholder, ctx) {
+    if (ctx.session)
+        throw new TemplateError(`a device session has no test files; {{${placeholder}}} only works in a queued run`);
+    const files = ctx.files ?? {};
+    const file = /^[a-z][a-z0-9_]{0,39}$/.test(fileName) && Object.hasOwn(files, fileName) ? files[fileName] : undefined;
+    if (!file)
+        throw new TemplateError(`the script uses {{${placeholder}}} but the job has no test file named ${fileName}`);
+    return file;
+}
+/**
+ * The files an `upload`, `drop_files` or `add_files` action hands over, as paths on this machine.
+ * Each entry is `{{file.<name>}}`, or a data placeholder whose value names a test file of the job;
+ * anything else is refused, so a script can never point the runner at its own files.
+ */
+export function resolveFileEntries(entries, ctx) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        throw new TemplateError('the action names no files');
+    return entries.map((entry, i) => {
+        const whole = /^\s*\{\{\s*([a-z][a-z0-9_.]*)\s*\}\}\s*$/.exec(typeof entry === 'string' ? entry : '');
+        const placeholder = whole?.[1];
+        let name;
+        if (placeholder?.startsWith('file.')) {
+            name = placeholder.slice('file.'.length);
+        }
+        else if (placeholder?.startsWith('data.')) {
+            name = dataValue(placeholder, ctx).trim();
+        }
+        else {
+            throw new TemplateError(`files[${i}] must be {{file.<name>}} or a test data placeholder naming a test file`);
+        }
+        const file = testFile(name, placeholder.startsWith('file.') ? placeholder : `file.${name}`, ctx);
+        if (!file.path)
+            throw new TemplateError(`test file ${name} is not ready on this runner`);
+        return { name, file, path: file.path };
+    });
+}
 /** A value only a queued job has: device sessions refuse it, and older servers may not send it. */
 function jobValue(ctx, name, value) {
     if (ctx.session)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leera.io/qa-runner",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Runs recorded QA test scripts on your own machines and reports results back to your workspace.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",