test-inventory 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # test-inventory
 
+## 0.3.0
+
+### Minor Changes
+
+- [#37](https://github.com/Huldoser/test-inventory/pull/37) [`5aeb139`](https://github.com/Huldoser/test-inventory/commit/5aeb13959daaeb0fdf4488765944fe42ef7754bc) - `--fields` keeps only the named keys of each test, and `id`, as in `--fields fullName,reason`, so a short question gets a short answer. Output written with it leaves keys out, so it no longer matches the JSON Schema. The library exports the same as `pickTestFields()`.
+
+- [#37](https://github.com/Huldoser/test-inventory/pull/37) [`5aeb139`](https://github.com/Huldoser/test-inventory/commit/5aeb13959daaeb0fdf4488765944fe42ef7754bc) - Filters keep only the tests a question is about: `--state`, `--tag`, `--grep` (a regular expression on the full name, ignoring case), `--only` and `--without-reason`, as in `--state skip --state fixme` for the tests that don't run. The output then describes only those tests: the describes around them, their diagnostics and a summary counted over them. The library exports the same as `filterInventory()`.
+
+- [#37](https://github.com/Huldoser/test-inventory/pull/37) [`5aeb139`](https://github.com/Huldoser/test-inventory/commit/5aeb13959daaeb0fdf4488765944fe42ef7754bc) - `--format jsonl` writes the inventory as JSON Lines: an `inventory` line, one line per suite, test and diagnostic, and a `summary` line, each marked with a `type` key. Tools that read one record per line, such as `grep` or DuckDB, no longer need the whole document in memory. The `InventoryLine` type describes the lines.
+
+### Patch Changes
+
+- [#34](https://github.com/Huldoser/test-inventory/pull/34) [`0f96258`](https://github.com/Huldoser/test-inventory/commit/0f96258e65085fa1b7c667b5fa7219a8b19230df) - A fixtures file that builds its test object with a function, written there or imported from another file, as in `export const test = defineDeskTest('equities')`, is followed: MSW's test files import such a `test`. Their tests were missing before, with no diagnostic when the fixtures file didn't import the framework itself. A test object built with a call the scan can't follow now gets an `unresolved-test-import` error that names the call, as in "builds it with withWarmup(), which is not followed". A function that returns what another function returns, as `() => onFeed('NYSE')`, is followed too.
+
+- [#34](https://github.com/Huldoser/test-inventory/pull/34) [`0f96258`](https://github.com/Huldoser/test-inventory/commit/0f96258e65085fa1b7c667b5fa7219a8b19230df) - A call the runner refuses that is written like a declaration, as `describe.sequential('title', fn)` in Vitest 5, `test('title', fn, { retry: 2 })` from Vitest 4 or `test.only.skip('title', fn)`, is listed as a plain test or describe without the part that fails. Its tests were missing before; now they are `notLoaded`, like every other test in the file.
+
+- [#34](https://github.com/Huldoser/test-inventory/pull/34) [`0f96258`](https://github.com/Huldoser/test-inventory/commit/0f96258e65085fa1b7c667b5fa7219a8b19230df) - States follow the runners' precedence more closely, as checked against Vitest 5.0.4 running generated files. A skip in a test or hook body loses to a fixme, skip or todo set while the file loads, as on a describe around the test, since the body never runs. In Vitest, a test's own options win over its chain, so `test.skip('title', { skip: false }, fn)` is active, but the chain still sets its mode: `test.concurrent('title', { concurrent: false }, fn)` runs in parallel. A describe passes its `skip` option down to the tests and describes inside, where it wins over todo, also when the describe's own `.only` keeps the describe itself from being skipped.
+
+## 0.2.1
+
+### Patch Changes
+
+- [#28](https://github.com/Huldoser/test-inventory/pull/28) [`04ff6d2`](https://github.com/Huldoser/test-inventory/commit/04ff6d2dd5a7ecc8fabffbf16b259fc9f2a68110) - A skip in a `catch` block, such as `context.skip()` when a test server can't start, is conditional, with the `catch` clause as its condition, as in `catch (error)`. It was recorded as an unconditional skip before. A test declared in a `catch` block gets `isInCondition: true`.
+
+- [#32](https://github.com/Huldoser/test-inventory/pull/32) [`3fcc933`](https://github.com/Huldoser/test-inventory/commit/3fcc93368dc9a4d810ff52b8d7d5fe4f99ca63ee) - Globs match folders and files whose names start with a dot, as in `.storybook/` or `.github/scripts/`, as they do in Playwright and Vitest; test files there were left out before. `.git` folders are always left out, like `node_modules`.
+
+- [#31](https://github.com/Huldoser/test-inventory/pull/31) [`631cc6b`](https://github.com/Huldoser/test-inventory/commit/631cc6b208aca5b28076da6eba33d8e6426ab778) - Workspace packages are found from both `pnpm-workspace.yaml` and the `workspaces` of `package.json`. When a repository had both, as after a move to pnpm that kept the old list, only `package.json` was read, and a package listed only in `pnpm-workspace.yaml` got an `unresolved-test-import` error.
+
+- [#30](https://github.com/Huldoser/test-inventory/pull/30) [`968e2bc`](https://github.com/Huldoser/test-inventory/commit/968e2bcd15c2157faae8fe91604634b1c1f68175) - A call through an imported name that reads like a test function is followed, and reported with `unresolved-test-import` when it can't be, also when it goes through a member the scan doesn't know, as in `it.effect('title', fn)` from `@effect/vitest`, or passes a timeout after the body, as in `test('title', fn, 60_000)`. Such tests were missing before, with no diagnostic. A module's own export of a name now wins over the same name passed on by `export *`, as in JavaScript: `export const it = ...` next to `export * from 'vitest'` is no longer read as Vitest's `it`.
+
+- [#28](https://github.com/Huldoser/test-inventory/pull/28) [`04ff6d2`](https://github.com/Huldoser/test-inventory/commit/04ff6d2dd5a7ecc8fabffbf16b259fc9f2a68110) - Tests on a test object that a function returns are found, as in `conditionalTest({ min: 22 })('title', fn)` or `const quoteTest = onNode(22)`, when the function is declared in the file or imported from a local file. They were missing before, with no diagnostic. When the function returns a different test function on different runs, as `it.skip` or `it`, only the modifiers they all have apply, as for a variable chosen by a condition. When the function can't be followed and its name reads like a test object, as for one from an installed package, the calls on what it returns are read as tests on trust, with a `local-test-object` warning.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -70,7 +70,9 @@ the first test's record includes:
 ```
 
 The output also has a `summary` with counts, a record for each describe, and `diagnostics` that point at code the
-scan could not read and values it could not work out.
+scan could not read and values it could not work out. Filters such as `--state skip`, `--tag @smoke` and
+`--grep "limit order"` keep only some tests, `--fields fullName,reason` keeps only some keys, and `--format jsonl`
+writes one record per line.
 
 ## Library
 

package/dist/ast.d.ts

@@ -4,6 +4,17 @@ export declare function childNodes(node: Node): Node[];
 /** Strips TypeScript-only wrappers such as `test!`, `test as any` and `<any>test`. */
 export declare function unwrap(node: Expression): Expression;
 export declare function isFunctionNode(node: Node | null | undefined): node is FunctionNode;
+/** A value a function returns, with the nodes inside the function around its `return`, outermost first. */
+export interface ReturnValue {
+    expression: Expression;
+    around: Node[];
+}
+/**
+ * The values a function returns; null when it may return no value, as with `return;` or no `return` at all, and for
+ * an async function or a generator, which returns a promise or an iterator whatever its `return` says. A `return` in a
+ * function inside it is that function's.
+ */
+export declare function returnValues(fn: FunctionNode): ReturnValue[] | null;
 export declare function isStringLiteral(node: Node): node is StringLiteral;
 /** `import.meta.vitest`, which in-source Vitest tests read their functions from. */
 export declare function isImportMetaVitest(expression: Expression): boolean;

package/dist/ast.js

@@ -32,6 +32,36 @@ export function unwrap(node) {
 export function isFunctionNode(node) {
     return node?.type === 'ArrowFunctionExpression' || node?.type === 'FunctionExpression';
 }
+/**
+ * The values a function returns; null when it may return no value, as with `return;` or no `return` at all, and for
+ * an async function or a generator, which returns a promise or an iterator whatever its `return` says. A `return` in a
+ * function inside it is that function's.
+ */
+export function returnValues(fn) {
+    if (fn.async || fn.generator)
+        return null;
+    // Only declarations of overloads have no body.
+    const body = fn.body;
+    if (body.type !== 'BlockStatement')
+        return [{ expression: body, around: [] }];
+    const values = [];
+    // Copied only at a `return`, so that a long function costs no more than its size.
+    const around = [];
+    const visit = (node) => {
+        if (node.type === 'ReturnStatement') {
+            values.push(node.argument ? { expression: node.argument, around: [...around] } : null);
+            return;
+        }
+        if (node.type === 'FunctionDeclaration' || isFunctionNode(node))
+            return;
+        around.push(node);
+        for (const child of childNodes(node))
+            visit(child);
+        around.pop();
+    };
+    visit(body);
+    return values.length > 0 && !values.includes(null) ? values : null;
+}
 export function isStringLiteral(node) {
     return node.type === 'Literal' && typeof node.value === 'string';
 }

package/dist/cli.d.ts

@@ -4,6 +4,6 @@ export interface Io {
     stderr: Writable;
     cwd: string;
 }
-export declare const HELP = "Usage: test-inventory <glob...> --framework <playwright|vitest> [options]\n\nLists the tests in the matching files as JSON, read from the source code without running them.\n\nOptions:\n  --framework <name>           playwright or vitest (required)\n  --root <dir>                 project root; paths in the output are relative to it (default: current directory)\n  --ignore <glob>              leave out matching files; can be repeated (node_modules is always left out)\n  --framework-version <x.y.z>  apply the rules of this framework version instead of the one in the project\n  --comments <mode>            comments above tests: all, non-active or none (default: non-active)\n  -o, --output <file>          write to a file instead of standard output\n  --pretty                     indent the JSON\n  -h, --help                   show this help\n  -v, --version                show the version\n\nExit codes: 0 when the scan finishes, even with diagnostics; 2 for invalid arguments, an output that cannot be\nwritten, or a crash. 1 is reserved for a future release.\n\nExample:\n  test-inventory \"tests/**/*.spec.ts\" --framework playwright --output inventory.json\n";
+export declare const HELP = "Usage: test-inventory <glob...> --framework <playwright|vitest> [options]\n\nLists the tests in the matching files as JSON, read from the source code without running them.\n\nOptions:\n  --framework <name>           playwright or vitest (required)\n  --root <dir>                 project root; paths in the output are relative to it (default: current directory)\n  --ignore <glob>              leave out matching files; can be repeated (node_modules is always left out)\n  --framework-version <x.y.z>  apply the rules of this framework version instead of the one in the project\n  --comments <mode>            comments above tests: all, non-active or none (default: non-active)\n  --state <state>              keep tests in this state, such as skip or fixme; can be repeated\n  --tag <tag>                  keep tests with this tag, such as @smoke; can be repeated\n  --grep <regex>               keep tests whose full name matches, ignoring case\n  --only                       keep tests that use .only, or are inside a describe that does\n  --without-reason             keep tests that don't run and give no reason\n  --fields <keys>              write only these keys of each test, separated by commas; id is always kept\n  --format <format>            json or jsonl, one record per line (default: json)\n  -o, --output <file>          write to a file instead of standard output\n  --pretty                     indent the JSON\n  -h, --help                   show this help\n  -v, --version                show the version\n\nExit codes: 0 when the scan finishes, even with diagnostics; 2 for invalid arguments, an output that cannot be\nwritten, or a crash. 1 is reserved for a future release.\n\nExamples:\n  test-inventory \"tests/**/*.spec.ts\" --framework playwright --output inventory.json\n  test-inventory \"tests/**/*.spec.ts\" --framework playwright --state skip --fields fullName,reason\n";
 /** Runs the command line with the given arguments and streams. Resolves to the exit code. */
 export declare function run(argv: string[], io: Io): Promise<number>;

package/dist/cli.js

@@ -3,7 +3,8 @@ import { once } from 'node:events';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { readFailure } from "./files.js";
-import { writeInventory } from "./json.js";
+import { checkFields, filterInventory, matcher, pickTestFields } from "./filter.js";
+import { writeInventory, writeInventoryLines } from "./json.js";
 import { OptionsError } from "./options.js";
 import { scan } from "./scan.js";
 import { toolVersion } from "./version.js";
@@ -17,6 +18,13 @@ Options:
   --ignore <glob>              leave out matching files; can be repeated (node_modules is always left out)
   --framework-version <x.y.z>  apply the rules of this framework version instead of the one in the project
   --comments <mode>            comments above tests: all, non-active or none (default: non-active)
+  --state <state>              keep tests in this state, such as skip or fixme; can be repeated
+  --tag <tag>                  keep tests with this tag, such as @smoke; can be repeated
+  --grep <regex>               keep tests whose full name matches, ignoring case
+  --only                       keep tests that use .only, or are inside a describe that does
+  --without-reason             keep tests that don't run and give no reason
+  --fields <keys>              write only these keys of each test, separated by commas; id is always kept
+  --format <format>            json or jsonl, one record per line (default: json)
   -o, --output <file>          write to a file instead of standard output
   --pretty                     indent the JSON
   -h, --help                   show this help
@@ -25,18 +33,24 @@ Options:
 Exit codes: 0 when the scan finishes, even with diagnostics; 2 for invalid arguments, an output that cannot be
 written, or a crash. 1 is reserved for a future release.
 
-Example:
+Examples:
   test-inventory "tests/**/*.spec.ts" --framework playwright --output inventory.json
+  test-inventory "tests/**/*.spec.ts" --framework playwright --state skip --fields fullName,reason
 `;
-/** CLI names for the option names in `scan()`'s errors. */
+/** CLI names for the option names in the library's errors. */
 const FLAGS = {
-    patterns: 'the glob patterns',
-    framework: '--framework',
-    root: '--root',
-    ignore: '--ignore',
-    frameworkVersion: '--framework-version',
-    comments: '--comments',
+    'options.patterns': 'the glob patterns',
+    'options.framework': '--framework',
+    'options.root': '--root',
+    'options.ignore': '--ignore',
+    'options.frameworkVersion': '--framework-version',
+    'options.comments': '--comments',
+    'filter.states': '--state',
+    'filter.tags': '--tag',
+    'filter.grep': '--grep',
+    fields: '--fields',
 };
+const FORMATS = ['json', 'jsonl'];
 async function writeTo(stream, chunk) {
     if (stream.errored)
         throw stream.errored;
@@ -89,6 +103,13 @@ export async function run(argv, io) {
                 ignore: { type: 'string', multiple: true },
                 'framework-version': { type: 'string' },
                 comments: { type: 'string' },
+                state: { type: 'string', multiple: true },
+                tag: { type: 'string', multiple: true },
+                grep: { type: 'string' },
+                only: { type: 'boolean' },
+                'without-reason': { type: 'boolean' },
+                fields: { type: 'string' },
+                format: { type: 'string' },
                 output: { type: 'string', short: 'o' },
                 pretty: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
@@ -112,8 +133,26 @@ export async function run(argv, io) {
         return fail('give at least one glob pattern for the test files.');
     if (values.framework === undefined)
         return fail('--framework is required: playwright or vitest.');
+    const format = values.format ?? 'json';
+    if (!FORMATS.includes(format))
+        return fail('--format must be json or jsonl.');
+    if (format === 'jsonl' && values.pretty)
+        return fail('--pretty indents JSON, so it does not go with --format jsonl.');
+    const filter = {
+        states: values.state,
+        tags: values.tag,
+        grep: values.grep,
+        only: values.only,
+        withoutReason: values['without-reason'],
+    };
+    const fields = values.fields?.split(',').map((field) => field.trim());
     let inventory;
+    let result;
     try {
+        // Checked before the scan, so a mistyped state or key doesn't wait for every file to be read.
+        matcher(filter);
+        if (fields !== undefined)
+            checkFields(fields);
         inventory = await scan({
             patterns: positionals,
             framework: values.framework,
@@ -122,10 +161,12 @@ export async function run(argv, io) {
             frameworkVersion: values['framework-version'],
             comments: values.comments,
         });
+        const filtered = filterInventory(inventory, filter);
+        result = fields === undefined ? filtered : pickTestFields(filtered, fields);
     }
     catch (error) {
         if (error instanceof OptionsError) {
-            return fail(error.message.replace(/^options\.(\w+)/, (_, name) => FLAGS[name]));
+            return fail(error.message.replace(/^[\w.]+/, (name) => FLAGS[name]));
         }
         io.stderr.write(`test-inventory: unexpected error: ${error instanceof Error ? String(error.stack) : String(error)}\n`);
         return FAILED;
@@ -139,8 +180,14 @@ export async function run(argv, io) {
     io.stdout.on('error', quiet);
     try {
         await writeOutput(io, values.output, async (output) => {
-            await writeInventory(inventory, values.pretty === true, (chunk) => writeTo(output, chunk));
-            await writeTo(output, '\n');
+            const write = (chunk) => writeTo(output, chunk);
+            if (format === 'jsonl') {
+                await writeInventoryLines(result, write);
+            }
+            else {
+                await writeInventory(result, values.pretty === true, write);
+                await write('\n');
+            }
         });
     }
     catch (error) {

package/dist/extract.js

@@ -1,4 +1,4 @@
-import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, unwrap } from "./ast.js";
+import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, returnValues, unwrap, } from "./ast.js";
 import { exportName } from "./frameworks/bindings.js";
 import { problem } from "./frameworks/common.js";
 import { snippet, splitLines } from "./source.js";
@@ -80,6 +80,8 @@ class Walker {
     callsWalked = 0;
     /** Problems already reported, since a function walked at several calls finds the same ones each time. */
     reported = new Set();
+    /** What the functions named in calls such as `onNode(22)('title', fn)` return, by the declaration of each name. */
+    returns = new Map();
     /** For each file's program, the scopes around each function in it. */
     scopeChains = new Map();
     constructor(main, openModule) {
@@ -178,6 +180,14 @@ class Walker {
                 this.visit(node.right, this.guarded(context, guard));
                 return;
             }
+            case 'TryStatement':
+                this.visit(node.block, context);
+                // A `catch` block runs only when the `try` block throws, as when a test server can't start.
+                if (node.handler)
+                    this.visit(node.handler, this.guarded(context, this.catchCondition(node.handler)));
+                if (node.finalizer)
+                    this.visit(node.finalizer, context);
+                return;
             case 'SwitchStatement': {
                 const discriminant = this.text(node.discriminant);
                 const values = node.cases.flatMap((switchCase) => (switchCase.test ? [this.text(switchCase.test)] : []));
@@ -241,6 +251,10 @@ class Walker {
             inBody: context.test !== null || context.hookScope !== null,
         };
     }
+    /** A `catch` block's condition, written as its clause: `catch` or `catch (error)`. */
+    catchCondition(handler) {
+        return this.text({ start: handler.start, end: handler.body.start }).trim();
+    }
     guarded(context, guard) {
         return { ...context, isInCondition: true, guards: guard === null ? context.guards : [...context.guards, guard] };
     }
@@ -280,6 +294,8 @@ class Walker {
             testContext: context.testContext,
             inTest: context.test !== null,
             inBody: context.test !== null || context.hookScope !== null,
+            passedDown: context.scope.suite?.declaration.passesDown ?? null,
+            returnsOf: (name, scopes) => this.returnsOf(name, scopes),
         });
         if (!api)
             return false;
@@ -308,6 +324,7 @@ class Walker {
                     reason: api.reason,
                     hasDynamicReason: api.hasDynamicReason,
                     line: this.lineOf(call),
+                    afterLoad: context.test !== null || context.hookScope !== null,
                 };
                 if (context.helper)
                     this.effectsOf(context.helper).push({ kind: 'state', setting, call });
@@ -345,7 +362,7 @@ class Walker {
             case 'invalid': {
                 const afterLoad = context.test !== null || context.hookScope !== null || context.helper !== null;
                 this.report(afterLoad ? { ...api.problem, afterLoad } : api.problem);
-                return true;
+                return api.declaration ? this.handle(call, api.declaration, context) : true;
             }
             case 'other':
                 return false;
@@ -379,7 +396,7 @@ class Walker {
         const fn = this.functionNamed(callee.name, this.scopes);
         if (!fn) {
             const runsHere = !context.test && !context.hookScope && !context.helper;
-            const imported = runsHere && this.callStack.length < MAX_DEPTH ? this.importedFunction(callee.name) : null;
+            const imported = runsHere && this.callStack.length < MAX_DEPTH ? this.importedFunction(callee.name, this.scopes) : null;
             return imported && !this.callStack.includes(imported.fn) ? this.withinLimit(imported, call) : null;
         }
         const sites = this.callSites.get(fn) ?? new Map();
@@ -414,14 +431,41 @@ class Walker {
         }
         return null;
     }
+    /**
+     * What a function declared in a file, the one being walked unless said otherwise, or imported from a local module,
+     * returns; null otherwise. Each declaration is looked up once, however many calls use it.
+     */
+    returnsOf(name, scopes, frame = this.frame) {
+        const declaration = frame.values.declarationOf(name, scopes);
+        if (declaration === null)
+            return null;
+        if (!this.returns.has(declaration)) {
+            const local = this.functionIn(frame, name, scopes);
+            const callee = local ? { fn: local, frame } : this.importedFunction(name, scopes, frame);
+            this.returns.set(declaration, callee && this.returnsIn(callee));
+        }
+        return this.returns.get(declaration) ?? null;
+    }
+    returnsIn({ fn, frame }) {
+        const scopes = [...this.scopeChain(fn, frame), fn];
+        const values = returnValues(fn)?.map(({ expression, around }) => ({
+            expression,
+            scopes: [...scopes, ...around.filter(isScopeNode)],
+        }));
+        return {
+            adapter: frame.adapter,
+            values: values ?? null,
+            returnsOf: (name, at) => this.returnsOf(name, at, frame),
+        };
+    }
     /** The function a name imported from a local module stands for, in the file that writes it; null otherwise. */
-    importedFunction(name) {
-        const declaration = this.frame.values.declarationOf(name, this.scopes);
-        const source = this.frame.values.importSource(name, this.scopes);
+    importedFunction(name, scopes, from = this.frame) {
+        const declaration = from.values.declarationOf(name, scopes);
+        const source = from.values.importSource(name, scopes);
         if (source === null)
             return null;
         const imported = declaration?.type === 'ImportSpecifier' ? exportName(declaration.imported) : 'default';
-        const frame = this.openFrom(this.frame, source);
+        const frame = this.openFrom(from, source);
         return frame ? this.exportedFunction(frame, imported, new Set(), 0) : null;
     }
     /** A module a file imports, read as a frame once; null when it can't be read or parsed. */
@@ -540,8 +584,8 @@ class Walker {
         this.parents.splice(0, this.parents.length, ...savedParents);
     }
     /** The scopes around a function where it is written, outermost first, to resolve names in it at its calls. */
-    scopeChain(fn) {
-        const { program } = this.frame.parsed;
+    scopeChain(fn, frame = this.frame) {
+        const { program } = frame.parsed;
         let chains = this.scopeChains.get(program);
         if (!chains) {
             const found = new Map();
@@ -645,7 +689,8 @@ class Walker {
                 if (effect.kind === 'configure')
                     return [effect];
                 const condition = joinConditions([...guards, ...(effect.setting.condition ? [effect.setting.condition] : [])]);
-                return [{ ...effect, setting: { ...effect.setting, condition } }];
+                // Helpers are expanded here only for calls from tests and hooks.
+                return [{ ...effect, setting: { ...effect.setting, condition, afterLoad: true } }];
             });
         };
         for (const call of this.helperCalls) {

package/dist/files.d.ts

@@ -12,7 +12,7 @@ export interface FoundFile {
  * left out for Playwright, which doesn't follow them, and read once for Vitest, which does, from the file's own path
  * when it matches too.
  */
-export declare function findFiles(root: string, patterns: string[], ignore: string[], framework: Framework): Promise<{
+export declare function findFiles(root: string, patterns: string[], ignore: string[], framework: Framework, platform?: NodeJS.Platform): Promise<{
     files: FoundFile[];
     diagnostics: Diagnostic[];
 }>;

package/dist/files.js

@@ -43,12 +43,14 @@ function recordingFs(failures) {
  * left out for Playwright, which doesn't follow them, and read once for Vitest, which does, from the file's own path
  * when it matches too.
  */
-export async function findFiles(root, patterns, ignore, framework) {
+export async function findFiles(root, patterns, ignore, framework, platform = process.platform) {
     const failures = [];
     // Only files match; a folder named like a test file, such as a screenshot folder `checkout.spec.ts/`, is not expanded.
-    const matches = await glob(patterns.map((pattern) => normalizePattern(pattern)), {
+    // As in both runners, names that start with a dot match too, as in `.storybook/`.
+    const matches = await glob(patterns.map((pattern) => normalizePattern(pattern, platform)), {
         cwd: root,
-        ignore: ['**/node_modules/**', ...ignore.map((pattern) => normalizePattern(pattern))],
+        dot: true,
+        ignore: ['**/node_modules/**', '**/.git/**', ...ignore.map((pattern) => normalizePattern(pattern, platform))],
         onlyFiles: true,
         expandDirectories: false,
         fs: recordingFs(failures),

package/dist/filter.d.ts

@@ -0,0 +1,37 @@
+import type { Inventory, TestRecord, TestState } from './types.ts';
+/** @inline */
+export interface InventoryFilter {
+    /** Keeps tests in one of these states. */
+    states?: TestState[];
+    /** Keeps tests with one of these tags, as the output writes them. */
+    tags?: string[];
+    /** Keeps tests whose `fullName` matches this regular expression, ignoring case, as Playwright's `--grep` does. */
+    grep?: string;
+    /** Keeps tests that use `.only`, or are inside a describe that does. */
+    only?: boolean;
+    /** Keeps tests that don't run and give no reason. Tests in a file the runner refuses are left out. */
+    withoutReason?: boolean;
+}
+/** An inventory whose test records have only `id` and the keys picked with `pickTestFields()`. */
+export type PickedInventory<K extends keyof TestRecord> = Omit<Inventory, 'tests'> & {
+    tests: Pick<TestRecord, 'id' | K>[];
+};
+/** Checks a filter and returns whether a test passes it. */
+export declare function matcher(filter: InventoryFilter): (test: TestRecord) => boolean;
+/**
+ * Keeps the tests that pass every condition of the filter; a list keeps a test that has any of its values. The
+ * result describes only those tests: the describes around them, their diagnostics, and a summary counted over them.
+ * `summary.fileCount` stays the number of files scanned.
+ *
+ * Throws a `TypeError` for an invalid filter.
+ */
+export declare function filterInventory(inventory: Inventory, filter: InventoryFilter): Inventory;
+/** Checks the keys to pick and returns them after `id`, each once. */
+export declare function checkFields(fields: unknown): (keyof TestRecord)[];
+/**
+ * Leaves only `id` and the given keys on each test record, in that order, to make the output smaller. Suites,
+ * diagnostics and the summary are unchanged. The result no longer matches the JSON Schema, which requires every key.
+ *
+ * Throws a `TypeError` for a key that test records don't have.
+ */
+export declare function pickTestFields<K extends keyof TestRecord>(inventory: Inventory, fields: readonly K[]): PickedInventory<K>;

package/dist/filter.js

@@ -0,0 +1,153 @@
+import { checkObject, OptionsError } from "./options.js";
+import { summarize } from "./summary.js";
+const STATES = ['active', 'skip', 'fixme', 'todo', 'expectedToFail', 'notLoaded'];
+const FILTER_KEYS = [
+    'states',
+    'tags',
+    'grep',
+    'only',
+    'withoutReason',
+];
+// Typed as a record of every key, so a key added to TestRecord fails to compile until it is listed here.
+const TEST_KEYS = Object.keys({
+    id: true,
+    bodyHash: true,
+    suiteId: true,
+    suitePath: true,
+    relativeFilePath: true,
+    fileName: true,
+    lineStart: true,
+    lineEnd: true,
+    columnStart: true,
+    columnEnd: true,
+    declaredAt: true,
+    title: true,
+    titleWithoutTags: true,
+    hasDynamicTitle: true,
+    fullName: true,
+    isTypeTest: true,
+    state: true,
+    isActive: true,
+    isSkipped: true,
+    isFixme: true,
+    isTodo: true,
+    isExpectedToFail: true,
+    isNotLoaded: true,
+    isOnly: true,
+    isConditional: true,
+    condition: true,
+    reason: true,
+    hasDynamicReason: true,
+    stateSource: true,
+    stateLine: true,
+    isParallel: true,
+    isSerial: true,
+    tags: true,
+    annotations: true,
+    comments: true,
+    locks: true,
+    meta: true,
+    isParameterized: true,
+    caseCount: true,
+    isInLoop: true,
+    isInCondition: true,
+    isInFunction: true,
+});
+function list(value, option, allowed) {
+    if (value === undefined)
+        return [];
+    const valid = (item) => typeof item === 'string' && item !== '' && (allowed === null || allowed.includes(item));
+    if (Array.isArray(value) && value.every(valid))
+        return value;
+    const bad = Array.isArray(value) ? value.find((item) => !valid(item)) : value;
+    const expected = allowed === null ? 'non-empty strings' : allowed.map((item) => `"${item}"`).join(', ');
+    throw new OptionsError(`${option} can only hold ${expected}; got ${JSON.stringify(bad)}.`);
+}
+function flag(value, option) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        throw new OptionsError(`${option} must be true or false.`);
+    return value;
+}
+function pattern(value) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || value === '')
+        throw new OptionsError('filter.grep must be a non-empty string.');
+    try {
+        return new RegExp(value, 'i');
+    }
+    catch (error) {
+        throw new OptionsError(`filter.grep must be a regular expression: ${error.message}.`);
+    }
+}
+/** Checks a filter and returns whether a test passes it. */
+export function matcher(filter) {
+    const checked = checkObject(filter, 'filter');
+    // A misspelled key would return every test, an answer that looks filtered but isn't.
+    const unknown = Object.keys(checked).find((key) => !FILTER_KEYS.includes(key));
+    if (unknown !== undefined) {
+        throw new OptionsError(`filter can only have the keys ${FILTER_KEYS.join(', ')}; got "${unknown}".`);
+    }
+    const states = list(checked.states, 'filter.states', STATES);
+    const tags = list(checked.tags, 'filter.tags', null);
+    const grep = pattern(checked.grep);
+    const only = flag(checked.only, 'filter.only');
+    const withoutReason = flag(checked.withoutReason, 'filter.withoutReason');
+    return (test) => (states.length === 0 || states.includes(test.state)) &&
+        (tags.length === 0 || test.tags.some((tag) => tags.includes(tag))) &&
+        (grep === null || grep.test(test.fullName)) &&
+        (!only || test.isOnly) &&
+        (!withoutReason || (!test.isActive && !test.isNotLoaded && test.reason === null));
+}
+/**
+ * Keeps the tests that pass every condition of the filter; a list keeps a test that has any of its values. The
+ * result describes only those tests: the describes around them, their diagnostics, and a summary counted over them.
+ * `summary.fileCount` stays the number of files scanned.
+ *
+ * Throws a `TypeError` for an invalid filter.
+ */
+export function filterInventory(inventory, filter) {
+    const tests = inventory.tests.filter(matcher(filter));
+    const testIds = new Set(tests.map((test) => test.id));
+    const parents = new Map(inventory.suites.map((suite) => [suite.id, suite.parentId]));
+    const suiteIds = new Set();
+    for (const test of tests) {
+        for (let id = test.suiteId; id !== null && !suiteIds.has(id); id = parents.get(id)) {
+            suiteIds.add(id);
+        }
+    }
+    const suites = inventory.suites.filter((suite) => suiteIds.has(suite.id));
+    const filesWithTests = new Set(inventory.tests.map((test) => test.relativeFilePath));
+    const filesWithMatches = new Set(tests.map((test) => test.relativeFilePath));
+    // A problem that is not about one test stays, unless every test of its file was left out: an error in a file
+    // with no tests, or in package.json, may mean tests are missing from the answer.
+    const diagnostics = inventory.diagnostics.filter((diagnostic) => diagnostic.testId === null
+        ? !filesWithTests.has(diagnostic.relativeFilePath) || filesWithMatches.has(diagnostic.relativeFilePath)
+        : testIds.has(diagnostic.testId));
+    const summary = summarize(inventory.summary.fileCount, suites, tests, diagnostics);
+    return { ...inventory, summary, suites, tests, diagnostics };
+}
+/** Checks the keys to pick and returns them after `id`, each once. */
+export function checkFields(fields) {
+    if (!Array.isArray(fields) || fields.length === 0) {
+        throw new OptionsError('fields must be a non-empty array of test record keys.');
+    }
+    const bad = fields.findIndex((field) => !TEST_KEYS.includes(field));
+    if (bad !== -1) {
+        throw new OptionsError(`fields can only hold keys of a test record, such as "fullName"; got ${JSON.stringify(fields[bad])}.`);
+    }
+    return [...new Set(['id', ...fields])];
+}
+/**
+ * Leaves only `id` and the given keys on each test record, in that order, to make the output smaller. Suites,
+ * diagnostics and the summary are unchanged. The result no longer matches the JSON Schema, which requires every key.
+ *
+ * Throws a `TypeError` for a key that test records don't have.
+ */
+export function pickTestFields(inventory, fields) {
+    const keys = checkFields(fields);
+    const tests = inventory.tests.map((test) => Object.fromEntries(keys.map((key) => [key, test[key]])));
+    return { ...inventory, tests };
+}