test-inventory 0.2.1 → 0.4.0

package/dist/extract.js

@@ -1,6 +1,6 @@
-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 { problem, readCount } from "./frameworks/common.js";
 import { snippet, splitLines } from "./source.js";
 import { isScopeNode } from "./values.js";
 /** How many helpers deep a call is followed into the functions it calls, far more than real suites nest. */
@@ -20,11 +20,49 @@ function calledWhereWritten(call, written) {
         !call.inBody);
 }
 const LOOP_METHODS = new Set(['forEach', 'map']);
-/** What `test.describe.configure()` sets on the describe or file it is called in: the last mode wins, locks add up. */
+/**
+ * What `test.describe.configure()` sets on the describe or file it is called in: the last mode, timeout and retries
+ * win, locks add up.
+ */
 function configure(scope, settings) {
     if (settings.mode)
         scope.mode = settings.mode;
     scope.details.locks.push(...settings.locks);
+    mergeRun(scope.details.run, settings.run);
+}
+/**
+ * Applies settings written later in the same place: the last value of each wins, and a test is slow when any
+ * `test.slow()` applies.
+ */
+export function mergeRun(target, later) {
+    const { slow, ...rest } = later;
+    Object.assign(target, rest);
+    if (slow)
+        target.slow = target.slow ? anySlow([target.slow, slow]) : slow;
+}
+/** Any of several `test.slow()` calls: always when one always applies, otherwise under any of their conditions. */
+export function anySlow(slows) {
+    const lists = slows.map((slow) => slow.conditions);
+    if (lists.includes(null))
+        return { conditions: null };
+    return { conditions: [...new Set(lists.flat())] };
+}
+/** Conditions joined with `||`, adding parentheses where a part could otherwise be read differently. */
+export function eitherCondition(parts) {
+    return parts.map((part) => (parts.length > 1 && /\?|,/.test(part) ? `(${part})` : part)).join(' || ');
+}
+/** A warning for a test or describe titled with an empty string, which reports can't tell apart. */
+function emptyTitle(declaration, call) {
+    const { title } = declaration;
+    if (title?.text !== '' || title.isDynamic)
+        return [];
+    const what = declaration.kind === 'test' ? 'test' : 'describe';
+    return [problem('empty-title', call, `The ${what} has an empty title, so reports and filters can't tell it apart.`)];
+}
+/** Hooks that run around each test, whose fixtures the test uses too. */
+const EACH_HOOKS = new Set(['beforeEach', 'afterEach', 'aroundEach']);
+export function noHooks() {
+    return { beforeAll: 0, beforeEach: 0, afterEach: 0, afterAll: 0, aroundEach: 0, aroundAll: 0 };
 }
 /** Joins conditions with `&&`, adding parentheses where a part could otherwise be read differently. */
 function joinConditions(parts) {
@@ -95,7 +133,10 @@ class Walker {
             states: [],
             mode: null,
             isOnly: false,
-            details: { tags: adapter.fileTags, annotations: [], locks: [], meta: null },
+            details: { tags: adapter.fileTags, annotations: [], locks: [], meta: null, run: {} },
+            hooks: noHooks(),
+            hookRun: {},
+            hookFixtures: [],
             suite: null,
         };
     }
@@ -104,6 +145,8 @@ class Walker {
             scope: this.fileScope,
             test: null,
             hookScope: null,
+            hookName: null,
+            stepDepth: 0,
             testContext: null,
             guards: [],
             isInLoop: false,
@@ -127,6 +170,7 @@ class Walker {
             suites: this.suites,
             tests: this.tests,
             problems: [...this.main.adapter.problems, ...this.problems],
+            hooks: this.fileScope.hooks,
             usesGlobals: this.main.adapter.usesGlobals,
         };
     }
@@ -147,6 +191,8 @@ class Walker {
     visitNode(node, context) {
         switch (node.type) {
             case 'CallExpression': {
+                if (context.test && !context.quiet)
+                    this.expectCall(node, context.test);
                 const helper = this.helperCall(node, context);
                 if (this.call(node, context) || this.loopCall(node, context))
                     return;
@@ -294,6 +340,7 @@ 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)
@@ -323,6 +370,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 });
@@ -340,13 +388,35 @@ class Walker {
                     configure(context.scope, api);
                 }
                 return true;
+            case 'run':
+                this.runSetting(call, api, context);
+                return true;
+            case 'step':
+                // The adapters only return steps from test bodies.
+                context.test.steps.push({
+                    title: api.title.text,
+                    hasDynamicTitle: api.title.isDynamic,
+                    lineStart: this.lineOf(call),
+                    depth: context.stepDepth,
+                    isSkipped: api.isSkipped,
+                });
+                if (api.fn)
+                    this.visitCallback(api.fn, { ...context, stepDepth: context.stepDepth + 1 });
+                return true;
             case 'hook':
                 if (context.test)
                     return false;
+                // A function with a name registers its hooks where it is called, not where it is written.
+                if (!context.hookScope && context.declaredIn === null) {
+                    context.scope.hooks[api.name] += 1;
+                    if (EACH_HOOKS.has(api.name))
+                        context.scope.hookFixtures.push(...api.fixtures);
+                }
                 if (api.fn) {
                     this.visitCallback(api.fn, {
                         ...context,
                         hookScope: context.scope,
+                        hookName: api.name,
                         testContext: api.testContext,
                         guards: [],
                         helper: null,
@@ -360,7 +430,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;
@@ -409,6 +479,7 @@ class Walker {
                 call,
                 fn,
                 target: context.test ?? context.hookScope,
+                hookName: context.test ? null : context.hookName,
                 guards: context.guards,
             });
         }
@@ -430,33 +501,40 @@ class Walker {
         return null;
     }
     /**
-     * What a function declared in the file being walked, or imported from a local module, returns; null otherwise. Each
-     * declaration is looked up once, however many calls use it.
+     * 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) {
-        const declaration = this.frame.values.declarationOf(name, scopes);
+    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.functionNamed(name, scopes);
-            const callee = local ? { fn: local, frame: this.frame } : this.importedFunction(name, scopes);
+            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 }) {
-        // An async function returns a promise, and a generator an iterator, whatever their `return` says.
-        const values = fn.async || fn.generator ? null : returnValues(fn, [...this.scopeChain(fn, frame), fn]);
-        return { adapter: frame.adapter, values };
+        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, scopes) {
-        const declaration = this.frame.values.declarationOf(name, scopes);
-        const source = this.frame.values.importSource(name, 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. */
@@ -598,6 +676,89 @@ class Walker {
         }
         return chains.get(fn);
     }
+    /**
+     * Applies `test.setTimeout()` or `test.slow()` where it is called: in a test body to the test, in a `beforeEach` to
+     * the tests of its scope, at file or describe level to the scope. A function with a name applies them where it is
+     * called instead.
+     */
+    runSetting(call, api, context) {
+        if (context.declaredIn !== null && !context.test) {
+            for (const item of api.problems)
+                this.report(item);
+            if (context.helper)
+                this.effectsOf(context.helper).push({ kind: 'run', settings: api.settings, argument: api.argument, call });
+            return;
+        }
+        const { settings, problems } = this.guardedRun(call, api.settings, api.argument, context.guards);
+        problems.unshift(...api.problems);
+        if (context.test) {
+            context.test.problems.push(...problems.map((item) => this.here(item)));
+            mergeRun(context.test.run, settings);
+            return;
+        }
+        for (const item of problems)
+            this.report(item);
+        if (context.hookScope) {
+            // `beforeAll` and `afterAll` set the hook's own timeout, and an `afterEach` runs after the test body.
+            if (context.hookName === 'beforeEach')
+                mergeRun(context.hookScope.hookRun, settings);
+            return;
+        }
+        mergeRun(context.scope.details.run, settings);
+    }
+    /**
+     * Run settings under the conditions around a call: a slow test keeps them as its condition, while a timeout set only
+     * sometimes is left out with a warning.
+     */
+    guardedRun(call, written, argument, guards) {
+        const settings = { ...written };
+        const problems = [];
+        const guard = joinConditions(guards);
+        if (settings.slow && guards.length > 0) {
+            const own = settings.slow.conditions ?? [null];
+            settings.slow = {
+                conditions: own.map((condition) => joinConditions([...guards, ...(condition === null ? [] : [condition])])),
+            };
+        }
+        if (settings.timeout !== undefined && guard !== null) {
+            const message = `Option timeout: ${argument} is set only when ${guard}; it is not applied.`;
+            problems.push(problem('unresolved-option', call, message, snippet(this.text(call))));
+            delete settings.timeout;
+        }
+        return { settings, problems };
+    }
+    /** Run settings a helper sets when a test body or a `beforeEach` calls it, under the conditions around the call. */
+    applyHelperRun(call, effect) {
+        const { settings, problems } = this.guardedRun(call.call, effect.settings, effect.argument, effect.guards);
+        if (call.hookName === null) {
+            const test = call.target;
+            test.problems.push(...problems);
+            mergeRun(test.run, settings);
+        }
+        else if (call.hookName === 'beforeEach') {
+            this.problems.push(...problems);
+            mergeRun(call.target.hookRun, settings);
+        }
+    }
+    /** Counts `expect()`, `expect.soft()` and `expect.poll()`, and reads `expect.assertions(n)` and `expect.hasAssertions()`. */
+    expectCall(call, test) {
+        const callee = unwrap(call.callee);
+        const [root, member] = callee.type === 'MemberExpression' ? [unwrap(callee.object), propertyName(callee)] : [callee, 'call'];
+        if (root.type !== 'Identifier' || root.name !== 'expect')
+            return;
+        if (member === 'call' || member === 'soft' || member === 'poll')
+            test.expectCount += 1;
+        if (member === 'hasAssertions')
+            test.expectsAssertions = true;
+        const count = call.arguments.at(0);
+        if (member === 'assertions' && count && count.type !== 'SpreadElement') {
+            const file = { source: this.frame.parsed.source, values: this.frame.values, version: null };
+            const option = { node: count, resolved: this.frame.values.resolve(count, this.scopes) };
+            const problems = [];
+            test.expectedAssertions = readCount(file, 'expect.assertions', option, problems);
+            test.problems.push(...problems.map((item) => this.here(item)));
+        }
+    }
     /** Reports a problem not tied to a test, once, however many times a function with it is walked. */
     report(found) {
         const item = this.here(found);
@@ -679,8 +840,11 @@ class Walker {
                     return expand(effect.fn, [...guards, ...effect.guards], new Set([...path, fn]));
                 if (effect.kind === 'configure')
                     return [effect];
+                if (effect.kind === 'run')
+                    return [{ ...effect, guards }];
                 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) {
@@ -690,6 +854,8 @@ class Walker {
                 // `describe.configure()` does nothing in a test or hook body.
                 if (effect.kind === 'state')
                     call.target.states.push(effect.setting);
+                if (effect.kind === 'run')
+                    this.applyHelperRun(call, effect);
             }
             if (steps > MAX_CALLS) {
                 const callee = snippet(this.frame.parsed.source.slice(call.call.callee.start, call.call.callee.end));
@@ -744,6 +910,7 @@ class Walker {
         if (context.quiet || this.nested(call, context))
             return;
         const statement = this.statement(call);
+        const empty = emptyTitle(declaration, call);
         const test = {
             scope: context.scope,
             declaration,
@@ -757,17 +924,26 @@ class Walker {
             isInCondition: context.isInCondition,
             isInFunction: context.isInFunction,
             comments: this.commentsAbove(statement.start),
-            problems: declaration.problems.map((item) => this.here(item)),
+            run: {},
+            expectCount: 0,
+            expectedAssertions: null,
+            expectsAssertions: false,
+            steps: [],
+            problems: [...declaration.problems, ...empty].map((item) => this.here(item)),
         };
         this.tests.push(test);
         if (context.declaredIn)
             this.declaredIn.set(test, context.declaredIn);
         this.cut(context.scope, call);
-        if (declaration.fn) {
-            this.visitCallback(declaration.fn, {
+        // A function declared in the file and passed by name runs as the test body too.
+        const body = declaration.fn ?? declaration.hashed;
+        if (body) {
+            this.visitCallback(body, {
                 ...context,
                 test,
                 hookScope: null,
+                hookName: null,
+                stepDepth: 0,
                 testContext: declaration.testContext,
                 guards: [],
                 helper: null,
@@ -777,7 +953,7 @@ class Walker {
     declareSuite(call, declaration, context) {
         if (context.quiet || this.nested(call, context))
             return;
-        for (const item of declaration.problems)
+        for (const item of [...declaration.problems, ...emptyTitle(declaration, call)])
             this.report(item);
         const scope = {
             kind: 'describe',
@@ -786,6 +962,9 @@ class Walker {
             mode: declaration.mode,
             isOnly: declaration.isOnly,
             details: declaration.details,
+            hooks: noHooks(),
+            hookRun: {},
+            hookFixtures: [],
             suite: null,
         };
         const suite = {
@@ -807,6 +986,8 @@ class Walker {
                 scope,
                 test: null,
                 hookScope: null,
+                hookName: null,
+                stepDepth: 0,
                 testContext: null,
                 guards: [],
                 helper: null,
@@ -843,31 +1024,6 @@ class Walker {
         return lines;
     }
 }
-/**
- * The values a function returns, each with the scopes around it, outermost first; null when it may return no value, as
- * with `return;` or no `return` at all. A `return` in a function inside it is that function's.
- */
-function returnValues(fn, scopes) {
-    // Only declarations of overloads have no body.
-    const body = fn.body;
-    if (body.type !== 'BlockStatement')
-        return [{ expression: body, scopes }];
-    const values = [];
-    const visit = (node, around) => {
-        if (node.type === 'ReturnStatement') {
-            values.push(node.argument ? { expression: node.argument, scopes: around } : null);
-            return;
-        }
-        if (node.type === 'FunctionDeclaration' || isFunctionNode(node))
-            return;
-        const inner = isScopeNode(node) ? [...around, node] : around;
-        for (const child of childNodes(node))
-            visit(child, inner);
-    };
-    visit(body, scopes);
-    const always = values.every((value) => value !== null);
-    return always && values.length > 0 ? values : null;
-}
 /** Walks the scanned file; `openModule` reads the modules of imported helpers that the file calls. */
 export function extract(main, openModule) {
     return new Walker(main, openModule).run();

package/dist/filter.d.ts

@@ -0,0 +1,38 @@
+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: their files, the describes around them, their diagnostics, and a summary
+ * counted over them. Files without any tests stay, with their diagnostics, since tests may be missing from 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,169 @@
+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,
+    hooks: true,
+    timeout: true,
+    isSlow: true,
+    slowCondition: true,
+    retries: true,
+    retryDelay: true,
+    retryCondition: true,
+    repeats: true,
+    fixtures: true,
+    expectCount: true,
+    expectedAssertions: true,
+    expectsAssertions: true,
+    hasEmptyBody: true,
+    steps: true,
+    isBenchmark: 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: their files, the describes around them, their diagnostics, and a summary
+ * counted over them. Files without any tests stay, with their diagnostics, since tests may be missing from 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 file, and a problem that is not about one test, stay unless every test of the 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 keepsFile = (relativeFilePath) => !filesWithTests.has(relativeFilePath) || filesWithMatches.has(relativeFilePath);
+    const diagnostics = inventory.diagnostics.filter((diagnostic) => diagnostic.testId === null ? keepsFile(diagnostic.relativeFilePath) : testIds.has(diagnostic.testId));
+    const summary = summarize(inventory.summary.fileCount, suites, tests, diagnostics);
+    const files = inventory.files.filter((file) => keepsFile(file.relativeFilePath));
+    return { ...inventory, summary, files, 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 };
+}