Expose test file path within worker process

This adds `test.meta.file` which exposes the filename of the test being run by AVA.

Fixes #1976

docs/01-writing-tests.md

@@ -267,6 +267,16 @@ test('context is unicorn', t => {
 });
 ```
 
+## Retrieving test meta data
+
+Helper files can determine the filename of the test being run by reading `test.meta.file`.  This eliminates the need to pass `__filename` from the test to helpers.
+
+```js
+import test from 'ava';
+
+console.log('Test currently being run: ', test.meta.file);
+```
+
 ## Reusing test logic through macros
 
 Additional arguments passed to the test declaration will be passed to the test implementation. This is useful for creating reusable test macros.

index.d.ts

@@ -468,6 +468,7 @@ export interface TestInterface<Context = {}> {
 	only: OnlyInterface<Context>;
 	skip: SkipInterface<Context>;
 	todo: TodoDeclaration;
+	meta: MetaInterface;
 }
 
 export interface AfterInterface<Context = {}> {
@@ -740,6 +741,11 @@ export interface TodoDeclaration {
 	(title: string): void;
 }
 
+export interface MetaInterface {
+	/** Path to the test file being executed. */
+	file: string;
+}
+
 /** Call to declare a test, or chain to declare hooks or test modifiers */
 declare const test: TestInterface;
 
@@ -776,6 +782,8 @@ export const skip: SkipInterface;
 /** Declare a test that should be implemented later. */
 export const todo: TodoDeclaration;
 
+/** Meta data associated with the current process. */
+export const meta: MetaInterface;
 
 /*
 Tail type from <https://github.com/tycho01/typical/blob/25f11ed92c960aab1ebbf47fd6ead9e0ae51d947/src/array/Tail.ts>.

index.js.flow

@@ -707,6 +707,7 @@ export interface SerialInterface<Context = {}> {
 	only: OnlyInterface<Context>;
 	skip: SkipInterface<Context>;
 	todo: TodoDeclaration;
+	meta: MetaInterface;
 }
 
 export interface SkipInterface<Context = {}> {
@@ -725,6 +726,11 @@ export interface TodoDeclaration {
 	(title: string): void;
 }
 
+export interface MetaInterface {
+	/** Path to the test file being executed. */
+	file: string;
+}
+
 /** Call to declare a test, or chain to declare hooks or test modifiers */
 declare export default TestInterface<>;
 
@@ -757,3 +763,6 @@ declare export var skip: SkipInterface<>;
 
 /** Declare a test that should be implemented later. */
 declare export var todo: TodoDeclaration;
+
+/** Meta data associated with the current process. */
+declare export var meta: MetaInterface;

lib/create-chain.js

@@ -61,7 +61,7 @@ function createHookChain(hook, isAfterHook) {
 	return hook;
 }
 
-function createChain(fn, defaults) {
+function createChain(fn, defaults, meta) {
 	// Test chaining rules:
 	// * `serial` must come at the start
 	// * `only` and `skip` must come at the end
@@ -108,6 +108,8 @@ function createChain(fn, defaults) {
 	root.todo = startChain('test.todo', fn, Object.assign({}, defaults, {type: 'test', todo: true}));
 	root.serial.todo = startChain('test.serial.todo', fn, Object.assign({}, defaults, {serial: true, type: 'test', todo: true}));
 
+	root.meta = meta;
+
 	return root;
 }
 

lib/runner.js

@@ -40,6 +40,9 @@ class Runner extends Emittery {
 		const uniqueTestTitles = new Set();
 		let hasStarted = false;
 		let scheduledStart = false;
+		const meta = Object.freeze({
+			file: options.file
+		});
 		this.chain = createChain((metadata, args) => { // eslint-disable-line complexity
 			if (hasStarted) {
 				throw new Error('All tests and hooks must be declared synchronously in your test file, and cannot be nested within other tests or hooks.');
@@ -159,7 +162,7 @@ class Runner extends Emittery {
 			failing: false,
 			callback: false,
 			always: false
-		});
+		}, meta);
 	}
 
 	compareTestSnapshot(options) {

test/api.js

@@ -71,6 +71,15 @@ test('async/await support', t => {
 		});
 });
 
+test('test.meta.file', t => {
+	const api = apiCreator();
+
+	return api.run([path.join(__dirname, 'fixture/meta.js')])
+		.then(runStatus => {
+			t.is(runStatus.stats.passedTests, 2);
+		});
+});
+
 test('fail-fast mode - single file & serial', t => {
 	const api = apiCreator({
 		failFast: true

test/fixture/meta.js

@@ -0,0 +1,9 @@
+import {default as test, meta} from '../..';
+
+test('meta.file', t => {
+	t.is(meta.file, __filename);
+});
+
+test('test.meta.file', t => {
+	t.is(test.meta.file, __filename);
+});