Experimentally implement t.like() assertion

Co-authored-by: Mark Wubben <mark@novemberborn.net>

docs/03-assertions.md

@@ -207,6 +207,55 @@ Assert that `value` is deeply equal to `expected`. See [Concordance](https://git
 
 Assert that `value` is not deeply equal to `expected`. The inverse of `.deepEqual()`.
 
+### `.like(value, selector, message?)`
+
+Assert that `value` is like `selector`. This is a variant of `.deepEqual()`, however `selector` does not need to have the same enumerable properties as `value` does.
+
+Instead AVA derives a *comparable* object from `value`, based on the deeply-nested properties of `selector`. This object is then compared to `selector` using `.deepEqual()`.
+
+Any values in `selector` that are not regular objects should be deeply equal to the corresponding values in `value`.
+
+This is an experimental assertion for the time being. You need to enable it:
+
+**`package.json`**:
+
+```json
+{
+	"ava": {
+		"nonSemVerExperiments": {
+			"likeAssertion": true
+		}
+	}
+}
+```
+
+**`ava.config.js`**:
+
+```js
+export default {
+	nonSemVerExperiments: {
+		likeAssertion: true
+	}
+}
+```
+
+In the following example, the `map` property of `value` must be deeply equal to that of `selector`. However `nested.qux` is ignored, because it's not in `selector`.
+
+```js
+t.like({
+	map: new Map([['foo', 'bar']]),
+	nested: {
+		baz: 'thud',
+		qux: 'quux'
+	}
+}, {
+	map: new Map([['foo', 'bar']]),
+	nested: {
+		baz: 'thud',
+	}
+})
+```
+
 ### `.throws(fn, expectation?, message?)`
 
 Assert that an error is thrown. `fn` must be a function which should throw. The thrown value *must* be an error. It is returned so you can run more assertions against it.

index.d.ts

@@ -45,6 +45,9 @@ export interface Assertions {
 	/** Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
 	deepEqual: DeepEqualAssertion;
 
+	/** Assert that `actual` is like `expected`. */
+	like: LikeAssertion;
+
 	/** Fail the test. */
 	fail: FailAssertion;
 
@@ -125,6 +128,14 @@ export interface DeepEqualAssertion {
 	skip(actual: any, expected: any, message?: string): void;
 }
 
+export interface LikeAssertion {
+	/** Assert that `value` is like `selector`. */
+	(value: any, selector: object, message?: string): void;
+
+	/** Skip this assertion. */
+	skip(value: any, selector: any, message?: string): void;
+}
+
 export interface FailAssertion {
 	/** Fail the test. */
 	(message?: string): void;

lib/assert.js

@@ -3,6 +3,7 @@ const concordance = require('concordance');
 const isError = require('is-error');
 const isPromise = require('is-promise');
 const concordanceOptions = require('./concordance-options').default;
+const {CIRCULAR_SELECTOR, isLikeSelector, selectComparable} = require('./like-selector');
 const snapshotManager = require('./snapshot-manager');
 
 function formatDescriptorDiff(actualDescriptor, expectedDescriptor, options) {
@@ -241,7 +242,8 @@ class Assertions {
 		fail = notImplemented,
 		skip = notImplemented,
 		compareWithSnapshot = notImplemented,
-		powerAssert
+		powerAssert,
+		experiments = {}
 	} = {}) {
 		const withSkip = assertionFn => {
 			assertionFn.skip = skip;
@@ -386,6 +388,61 @@ class Assertions {
 			}
 		});
 
+		this.like = withSkip((actual, selector, message) => {
+			if (!experiments.likeAssertion) {
+				fail(new AssertionError({
+					assertion: 'like',
+					improperUsage: true,
+					message: 'You must enable the `likeAssertion` experiment in order to use `t.like()`'
+				}));
+				return;
+			}
+
+			if (!checkMessage('like', message)) {
+				return;
+			}
+
+			if (!isLikeSelector(selector)) {
+				fail(new AssertionError({
+					assertion: 'like',
+					improperUsage: true,
+					message: '`t.like()` selector must be a non-empty object',
+					values: [formatWithLabel('Called with:', selector)]
+				}));
+				return;
+			}
+
+			let comparable;
+			try {
+				comparable = selectComparable(actual, selector);
+			} catch (error) {
+				if (error === CIRCULAR_SELECTOR) {
+					fail(new AssertionError({
+						assertion: 'like',
+						improperUsage: true,
+						message: '`t.like()` selector must not contain circular references',
+						values: [formatWithLabel('Called with:', selector)]
+					}));
+					return;
+				}
+
+				throw error;
+			}
+
+			const result = concordance.compare(comparable, selector, concordanceOptions);
+			if (result.pass) {
+				pass();
+			} else {
+				const actualDescriptor = result.actual || concordance.describe(comparable, concordanceOptions);
+				const expectedDescriptor = result.expected || concordance.describe(selector, concordanceOptions);
+				fail(new AssertionError({
+					assertion: 'like',
+					message,
+					values: [formatDescriptorDiff(actualDescriptor, expectedDescriptor)]
+				}));
+			}
+		});
+
 		this.throws = withSkip((...args) => {
 			// Since arrow functions do not support 'arguments', we are using rest
 			// operator, so we can determine the total number of arguments passed

lib/like-selector.js

@@ -0,0 +1,37 @@
+'use strict';
+function isLikeSelector(selector) {
+	return selector !== null &&
+		typeof selector === 'object' &&
+		Reflect.getPrototypeOf(selector) === Object.prototype &&
+		Reflect.ownKeys(selector).length > 0;
+}
+
+exports.isLikeSelector = isLikeSelector;
+
+const CIRCULAR_SELECTOR = new Error('Encountered a circular selector');
+exports.CIRCULAR_SELECTOR = CIRCULAR_SELECTOR;
+
+function selectComparable(lhs, selector, circular = new Set()) {
+	if (circular.has(selector)) {
+		throw CIRCULAR_SELECTOR;
+	}
+
+	circular.add(selector);
+
+	if (lhs === null || typeof lhs !== 'object') {
+		return lhs;
+	}
+
+	const comparable = {};
+	for (const [key, rhs] of Object.entries(selector)) {
+		if (isLikeSelector(rhs)) {
+			comparable[key] = selectComparable(Reflect.get(lhs, key), rhs, circular);
+		} else {
+			comparable[key] = Reflect.get(lhs, key);
+		}
+	}
+
+	return comparable;
+}
+
+exports.selectComparable = selectComparable;

lib/load-config.js

@@ -7,7 +7,7 @@ const pkgConf = require('pkg-conf');
 
 const NO_SUCH_FILE = Symbol('no ava.config.js file');
 const MISSING_DEFAULT_EXPORT = Symbol('missing default export');
-const EXPERIMENTS = new Set(['reverseTeardowns']);
+const EXPERIMENTS = new Set(['likeAssertion', 'reverseTeardowns']);
 
 // *Very* rudimentary support for loading ava.config.js files containing an `export default` statement.
 const evaluateJsConfig = configFile => {

lib/test.js

@@ -39,7 +39,8 @@ class ExecutionContext extends assert.Assertions {
 			compareWithSnapshot: options => {
 				return test.compareWithSnapshot(options);
 			},
-			powerAssert: test.powerAssert
+			powerAssert: test.powerAssert,
+			experiments: test.experiments
 		});
 		testMap.set(this, test);
 

test-d/like.ts

@@ -0,0 +1,17 @@
+import test from '..';
+
+test('like', t => {
+	t.like({
+		map: new Map([['foo', 'bar']]),
+		nested: {
+			baz: 'thud',
+			qux: 'quux'
+		}
+	}, {
+		map: new Map([['foo', 'bar']]),
+		nested: {
+			baz: 'thud'
+		}
+	});
+});
+