Expose internal events for custom reporters via config

entrypoints/internal.cjs

@@ -0,0 +1 @@
+module.exports = {};

entrypoints/internal.d.cts

@@ -0,0 +1 @@
+export * from "./internal"

entrypoints/internal.d.mts

@@ -0,0 +1 @@
+export * from "./internal"

entrypoints/internal.d.ts

@@ -0,0 +1,25 @@
+import type {StateChangeEvent} from '../types/state-change-events.d.cts';
+
+export type RunEvent = {
+	type: 'stateChange';
+	stateChange: StateChangeEvent;
+} | {
+	type: 'run';
+	plan: {
+		bailWithoutReporting: boolean;
+		debug: boolean;
+		failFastEnabled: boolean;
+		filePathPrefix: string;
+		files: string[];
+		matching: boolean;
+		previousFailures: number;
+		runOnlyExclusive: boolean;
+		firstRun: boolean;
+	};
+};
+
+export type {StateChangeEvent} from '../types/state-change-events.d.cts';
+
+export type Run = {
+	events: AsyncIterableIterator<RunEvent>;
+};

entrypoints/internal.mjs

@@ -0,0 +1 @@
+export {};

internal.d.ts

@@ -0,0 +1,3 @@
+// For compatibility with resolution algorithms other than Node16.
+
+export * from './entrypoints/internal.cjs';

lib/api-event-iterator.js

@@ -0,0 +1,17 @@
+import {on} from 'node:events';
+
+export async function * asyncEventIteratorFromApi(api) {
+	for await (const [plan] of on(api, 'run')) {
+		yield {
+			type: 'run',
+			plan,
+		};
+
+		for await (const [stateChange] of on(plan.status, 'stateChange')) {
+			yield {
+				type: 'stateChange',
+				stateChange,
+			};
+		}
+	}
+}

lib/cli.js

@@ -8,6 +8,7 @@ import figures from 'figures';
 import yargs from 'yargs';
 import {hideBin} from 'yargs/helpers'; // eslint-disable-line n/file-extension-in-import
 
+import {asyncEventIteratorFromApi} from './api-event-iterator.js';
 import Api from './api.js';
 import {chalk} from './chalk.js';
 import validateEnvironmentVariables from './environment-variables.js';
@@ -471,10 +472,16 @@ export default async function loadCli() { // eslint-disable-line complexity
 		});
 	}
 
-	api.on('run', plan => {
+	if (combined.observeRun && experiments.observeRunsFromConfig) {
+		combined.observeRun({
+			events: asyncEventIteratorFromApi(api),
+		});
+	}
+
+	api.on('run', async plan => {
 		reporter.startRun(plan);
 
-		plan.status.on('stateChange', evt => {
+		plan.status.on('stateChange', async evt => {
 			if (evt.type === 'end' || evt.type === 'interrupt') {
 				// Write out code coverage data when the run ends, lest a process
 				// interrupt causes it to be lost.

lib/load-config.js

@@ -8,7 +8,7 @@ import {packageConfig, packageJsonPath} from 'pkg-conf';
 
 const NO_SUCH_FILE = Symbol('no ava.config.js file');
 const MISSING_DEFAULT_EXPORT = Symbol('missing default export');
-const EXPERIMENTS = new Set();
+const EXPERIMENTS = new Set(['observeRunsFromConfig']);
 
 const importConfig = async ({configFile, fileForErrorMessage}) => {
 	const {default: config = MISSING_DEFAULT_EXPORT} = await import(url.pathToFileURL(configFile));

package.json

@@ -29,6 +29,16 @@
 				"types": "./entrypoints/plugin.d.cts",
 				"default": "./entrypoints/plugin.cjs"
 			}
+		},
+		"./internal": {
+			"import": {
+				"types": "./entrypoints/internal.d.mts",
+				"default": "./entrypoints/internal.mjs"
+			},
+			"require": {
+				"types": "./entrypoints/internal.d.cts",
+				"default": "./entrypoints/internal.cjs"
+			}
 		}
 	},
 	"type": "module",

test/internal-events/fixtures/.gitignore

@@ -0,0 +1 @@
+internal-events.json

test/internal-events/fixtures/ava.config.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs/promises';
+
+const internalEvents = [];
+
+export default {
+	files: [
+		'test.js',
+	],
+	nonSemVerExperiments: {
+		observeRunsFromConfig: true,
+	},
+	async observeRun(run) {
+		for await (const event of run.events) {
+			internalEvents.push(event);
+
+			if (event.type === 'stateChange' && event.stateChange.type === 'end') {
+				await fs.writeFile('internal-events.json', JSON.stringify(internalEvents));
+			}
+		}
+	},
+};

test/internal-events/fixtures/package.json

@@ -0,0 +1,3 @@
+{
+	"type": "module"
+}

test/internal-events/fixtures/test.js

@@ -0,0 +1,5 @@
+import test from 'ava';
+
+test('placeholder', t => {
+	t.pass();
+});

test/internal-events/test.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+
+import test from '@ava/test';
+
+import {fixture} from '../helpers/exec.js';
+
+test('internal events are emitted', async t => {
+	await fixture();
+
+	const result = JSON.parse(await fs.readFile(fileURLToPath(new URL('fixtures/internal-events.json', import.meta.url))));
+
+	t.like(result[0], {
+		type: 'run',
+		plan: {
+			files: [
+				fileURLToPath(new URL('fixtures/test.js', import.meta.url)),
+			],
+		},
+	});
+
+	const testPassedEvent = result.find(event => event.type === 'stateChange' && event.stateChange.type === 'test-passed');
+	t.like(testPassedEvent, {
+		type: 'stateChange',
+		stateChange: {
+			type: 'test-passed',
+			title: 'placeholder',
+			testFile: fileURLToPath(new URL('fixtures/test.js', import.meta.url)),
+		},
+	});
+
+	t.like(result[result.length - 1], {
+		type: 'stateChange',
+		stateChange: {
+			type: 'end',
+		},
+	});
+});

types/state-change-events.d.cts

@@ -0,0 +1,143 @@
+type ErrorSource = {
+  isDependency: boolean
+  isWithinProject: boolean
+  file: string
+  line: number
+}
+
+type SerializedErrorBase = {
+  message: string
+  name: string,
+  originalError: unknown,
+  stack: string
+}
+
+type AggregateSerializedError = SerializedErrorBase & {
+  type: "aggregate"
+  errors: SerializedError[]
+}
+
+type NativeSerializedError = SerializedErrorBase & {
+  type: "native"
+  source: ErrorSource | null
+}
+
+type AVASerializedError = SerializedErrorBase & {
+  type: "ava"
+  assertion: string
+  improperUsage: unknown | null
+  formattedCause: unknown | null
+  formattedDetails: unknown | unknown[]
+  source: ErrorSource | null
+}
+
+type SerializedError = AggregateSerializedError | NativeSerializedError | AVASerializedError
+
+export type StateChangeEvent = {
+  type: "starting",
+  testFile: string
+} | {
+  type: "stats",
+  stats: {
+    byFile: Map<string, {
+      declaredTests: number
+      failedHooks: number,
+      failedTests: number,
+      internalErrors: number
+      remainingTests: number,
+      passedKnownFailingTests: number,
+      passedTests: number,
+      selectedTests: number,
+      selectingLines: boolean,
+      skippedTests: number,
+      todoTests: number,
+      uncaughtExceptions: number,
+      unhandledRejections: number,
+    }>
+    declaredTests: number
+    failedHooks: number,
+    failedTests: number,
+    failedWorkers: number,
+    files: number,
+    parallelRuns: {
+      currentIndex: number,
+      totalRuns: number
+    } | null
+    finishedWorkers: number,
+    internalErrors: number
+    remainingTests: number,
+    passedKnownFailingTests: number,
+    passedTests: number,
+    selectedTests: number,
+    sharedWorkerErrors: number,
+    skippedTests: number,
+    timedOutTests: number,
+    timeouts: number,
+    todoTests: number,
+    uncaughtExceptions: number,
+    unhandledRejections: number,
+  }
+} | {
+  type: "declared-test"
+  title: string
+  knownFailing: boolean
+  todo: boolean
+  testFile: string
+} | {
+  type: "selected-test"
+  title: string
+  knownFailing: boolean
+  skip: boolean
+  todo: boolean
+  testFile: string
+} | {
+  type: "test-register-log-reference"
+  title: string
+  logs: string[]
+  testFile: string
+} | {
+  type: "test-passed",
+  title: string
+  duration: number
+  knownFailing: boolean
+  logs: string[]
+  testFile: string
+} | {
+  type: "test-failed",
+  title: string
+  err: SerializedError,
+  duration: number
+  knownFailing: boolean
+  logs: string[]
+  testFile: string
+} | {
+  type: "worker-finished",
+  forcedExit: boolean,
+  testFile: string
+} | {
+  type: "worker-failed",
+  nonZeroExitCode?: boolean,
+  signal?: string,
+  err?: SerializedError
+} | {
+  type: "touched-files",
+  files: {
+    changedFiles: string[],
+    temporaryFiles: string[]
+  }
+} | {
+  type: 'worker-stdout',
+  chunk: Uint8Array
+  testFile: string
+} | {
+  type: 'worker-stderr',
+  chunk: Uint8Array
+  testFile: string
+} | {
+  type: "timeout",
+  period: number,
+  pendingTests: Map<string, Set<string>>
+}
+ | {
+  type: "end"
+}