Add tests and testEngine.detail() method.

Author: sholladay

README.md

@@ -56,24 +56,13 @@ Ask for a more detailed report.
 
 ```js
 testEngine(null, null, { detail : true })
-    .then((engines) => {
-        console.log(engines);
-        // {
-        //     allSatisfied : false,
-        //     satisfied : {
-        //         npm : {
-        //             expected : '^2.0.0',
-        //             actual   : '2.14.2'
-        //         }
-        //     },
-        //     notSatisfied : {
-        //         node : {
-        //             expected : '>4.2.0',
-        //             actual   : '4.0.0'
-        //         }
-        //     }
-        // }
-    });
+    .then(console.log);
+    // {
+    //     allSatisfied : true,
+    //     satisfied : {
+    //         npm : { actual : '4.0.0', expected : '>=4' }
+    //     }
+    // }
 ```
 
 You can register a handler that will only run when the user has compatible engines.
@@ -86,6 +75,60 @@ testEngine.assert().then(() => {
 });
 ```
 
+## API
+
+### testEngine(wanted, known, option)
+
+Returns a `Promise` for a report of whether the `known` engines [satisfy](https://github.com/npm/node-semver#ranges) the `wanted` engines.
+
+### testEngine.detail(wanted, known)
+
+Same as `testEngine()` with the `detail` option set to true.
+
+### testEngine.assert(wanted, known)
+
+Returns a `Promise` for a detailed report asserting that the `wanted` engines are satisfied. If they are not, the promise is rejected with an error whose `engine` field has the report.
+
+#### wanted
+
+Type: `string` or `object`<br>
+Default: `process.cwd()`
+
+A path to start a [find-up](https://github.com/sindresorhus/find-up) search for a package.json with an `engines` field. Or an explicit object of the same form as the `engines` field.
+
+#### known
+
+Type: `object`
+
+An object of key/value pairs for engine names and their respective versions to compare against `wanted`. Fields for `node` and `npm` will be filled in if necessary according to the engines in `wanted`. However, they can be provided here as overrides.
+
+#### option
+
+Type: `object`
+
+Settings for how to report the result.
+
+##### detail
+
+Type: `boolean`<br>
+Default: `false`
+
+Report the result as an object with individual fields for each engine rather than a simple boolean.
+
+Example:
+
+```js
+{
+    allSatisfied : false,
+    satisfied : {
+        npm : { actual : '4.0.0', expected : '>=4' }
+    },
+    notSatisfied : {
+        node : { actual : '7.0.0', expected : '>=8' }
+    }
+}
+```
+
 ## Contributing
 
 See our [contributing guidelines](https://github.com/sholladay/test-engine/blob/master/CONTRIBUTING.md "The guidelines for participating in this project.") for more details.

index.js

@@ -100,37 +100,29 @@ const testEngine = async (wanted, known, option) => {
                 result.notSatisfied = {};
             }
             result.notSatisfied[name] = data;
-            // If any engine is bad, flip the switch that informs
-            // the user, so that they don't have to loop through
-            // the result themselves in order to determine that,
-            // which would duplicate some effort.
             result.allSatisfied = false;
         }
     });
 
     return result;
 };
 
-// When no expectations are provided, testEngine() tries to figure them out
-// based on the caller's package.json. But since we are an intermediary,
-// our own module is the caller. So we forward our caller's path
-// with the same logic used by testEngine().
-testEngine.assert = async (wanted, known, option) => {
+testEngine.detail = (wanted, known, option) => {
     const config = Object.assign({}, option, {
         detail : true
     });
+    return testEngine(wanted, known, config);
+};
 
-    const engine = await testEngine(wanted, known, config);
+testEngine.assert = async (...args) => {
+    const engine = await testEngine.detail(...args);
     if (engine.allSatisfied) {
         return engine;
     }
 
-    let errMessage = 'Your engines are not compatible:\n';
-    const { notSatisfied } = engine;
-    Object.keys(notSatisfied).forEach((name) => {
-        const { actual, expected } = notSatisfied[name];
-        errMessage += `  ${name} ${actual} (expected ${expected})\n`;
-    });
+    const errMessage = Object.entries(engine.notSatisfied).reduce((msg, [name, val]) => {
+        return msg + `  ${name} ${val.actual}, expected ${val.expected}\n`;
+    }, 'Your engines are not compatible:\n');
 
     const err = new RangeError(errMessage);
     err.engine = engine;

package.json

@@ -10,7 +10,7 @@
     "email": "[email protected]"
   },
   "scripts": {
-    "test": "xo"
+    "test": "xo && ava"
   },
   "repository": {
     "type": "git",
@@ -33,6 +33,7 @@
     "semver": "^5.3.0"
   },
   "devDependencies": {
+    "ava": "^0.18.1",
     "eslint-config-tidy": "^0.4.0",
     "xo": "^0.17.1"
   },

test.js

@@ -0,0 +1,75 @@
+import os from 'os';
+import test from 'ava';
+import semver from 'semver';
+import testEngine from './';
+
+test('is supported', async (t) => {
+    const isSupported = await testEngine();
+    t.is(typeof isSupported, 'boolean');
+    t.true(isSupported);
+    await t.notThrows(testEngine.assert());
+});
+
+test('detailed report', async (t) => {
+    const engine = await testEngine.detail();
+    t.truthy(engine);
+    t.is(typeof engine, 'object');
+    const ownProps = Object.getOwnPropertyNames(engine);
+    t.is(ownProps.length, 2);
+    t.true(ownProps.includes('allSatisfied'));
+    t.true(ownProps.includes('satisfied'));
+    t.deepEqual(ownProps, [
+        'allSatisfied',
+        'satisfied'
+    ]);
+    t.true(engine.allSatisfied);
+    t.false('notSatisfied' in engine);
+    const { satisfied } = engine;
+    t.truthy(satisfied);
+    t.is(typeof satisfied, 'object');
+    t.true(Object.prototype.hasOwnProperty.call(satisfied, 'node'));
+    t.truthy(satisfied.node);
+    t.is(typeof satisfied.node, 'object');
+    t.truthy(satisfied.node.actual);
+    t.is(typeof satisfied.node.actual, 'string');
+    t.truthy(satisfied.node.expected);
+    t.is(typeof satisfied.node.expected, 'string');
+    t.true(semver.satisfies(satisfied.node.actual, satisfied.node.expected));
+});
+
+test('custom cwd', async (t) => {
+    const nonPkgDir = os.tmpdir();
+    const isSupported = await testEngine(nonPkgDir, {
+        node : '0.0.1',
+        npm  : '0.0.1'
+    });
+    t.true(isSupported);
+
+    const engine = await testEngine.detail(nonPkgDir, {
+        node : '0.0.1',
+        npm  : '0.0.1'
+    });
+    t.truthy(engine);
+    t.is(typeof engine, 'object');
+    t.true(engine.allSatisfied);
+    t.deepEqual(engine, {
+        allSatisfied : true
+    });
+});
+
+test('.assert() returns report if supported', async (t) => {
+    const engine = await t.notThrows(testEngine.assert());
+    t.truthy(engine);
+    t.is(typeof engine, 'object');
+    t.true(engine.allSatisfied);
+    t.false('notSatisfied' in engine);
+});
+
+test('.assert() throws if unsupported', async (t) => {
+    const err = await t.throws(testEngine.assert(null, { node : '0.10.0' }), RangeError);
+    t.truthy(err.engine);
+    t.is(typeof err.engine, 'object');
+    t.true(Object.prototype.hasOwnProperty.call(err, 'engine'));
+    t.false(err.engine.allSatisfied);
+    t.false('satisfied' in err.engine);
+});