Merge pull request #42 from apiaryio/honzajavorek/cli

Add CLI

.circleci/config.yml

@@ -16,7 +16,7 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Install dev dependencies (Node.js)
+          name: Install dependencies (Node.js)
           command: npm install
       - run:
           name: Install the reference hooks implementation (Python)

.gitignore

@@ -1,2 +1,2 @@
 node_modules
-test
+dredd-hooks-template-*.tgz

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Clone the repository and install dependencies:
+
+```
+$ git clone "https://github.com/apiaryio/dredd-hooks-template.git"
+$ cd ./dredd-hooks-template
+$ npm install
+```
+
+## Smoke Test
+
+There is a [smoke test](https://en.wikipedia.org/wiki/Smoke_testing_(software)), which ensures everything works as described in the tutorial above. It uses the [Python hooks handler](https://github.com/apiaryio/dredd-hooks-python) as the reference implementation, so have it installed:
+
+```
+$ pip install dredd_hooks
+```
+
+Then you can run the smoke test:
+
+```
+$ npm test
+```
+
+## Feature Files Linter
+
+The feature files syntax is validated automatically. To perform the validation locally, use the `lint` script:
+
+```
+$ npm run lint
+```
+
+## Introducing Changes
+
+The test suite uses the [Python hooks](https://github.com/apiaryio/dredd-hooks-python) as a reference implementation. To introduce a change to this test suite, follow these steps:
+
+1.  Implement the new behavior in the Python hooks.
+1.  Change the feature files living in the Python hooks repo to describe the new behavior. If needed, add a local `steps.js` file implementing missing test steps.
+1.  Make sure the Python hooks pass that changed test suite.
+1.  Release a new version of the Python hooks.
+1.  Generalize the changed (or added) feature files with placeholders, comment-out the code examples, and copy the files over to this repository. Add missing test steps implementations to the `steps.js`. Create a Pull Request.
+1.  Make sure the smoke test passes under the Pull Request.
+1.  Merge the Pull Request and let Semantic Release to produce a new version of the test suite package.
+1.  Go to Python hooks repository and [upgrade](README.md#upgrading) the test suite package there. Remove any local `steps.js` as the necessary steps should already be implemented in the new version of the test suite package.
+1.  Go to Ruby hooks repository and [upgrade](README.md#upgrading) the test suite package there.
+1.  Go to all remaining repositories with hooks handlers and issue Pull Requests for the maintainers which help them to kick-off the upgrade. It's okay if they're incomplete, their purpose is to advertise the changes, to initiate the upgrade, and to be helpful to the maintainers.

README.md

@@ -1,63 +1,60 @@
-# Cross-Language Test Suite for Dredd Hooks
+# Cross-Language Test Suite for Dredd Hooks Handlers
 
-[![Build Status](https://travis-ci.org/apiaryio/dredd-hooks-template.svg?branch=master)](https://travis-ci.org/apiaryio/dredd-hooks-template) [![Greenkeeper badge](https://badges.greenkeeper.io/apiaryio/dredd-hooks-template.svg)](https://greenkeeper.io/)
+[![Build Status](https://travis-ci.org/apiaryio/dredd-hooks-template.svg?branch=master)](https://travis-ci.org/apiaryio/dredd-hooks-template)
 
-Language-agnostic BDD test suite for boilerplating implementation of [Dredd][] [hooks][] handler for a new language. It tests the public interface of the hooks handler and ensures it will work as Dredd expects. It's written in [Gherkin][] and ran by [Aruba][].
+[Dredd](https://dredd.org) is a tool for testing web APIs. It supports [hooks](http://dredd.org/en/latest/hooks/index.html) written in [many languages](http://dredd.org/en/latest/hooks/index.html#supported-languages). To support a particular language, it needs an adapter, so-called hooks handler. This [BDD](https://en.wikipedia.org/wiki/Behavior-driven_development) test suite ensures that the public interface of each hooks handler works as Dredd expects. The test suite is written in [Gherkin](https://github.com/cucumber/cucumber/wiki/Gherkin) and uses [Cucumber](https://github.com/cucumber/cucumber-js) as a test runner.
 
-  [Aruba]: https://github.com/cucumber/aruba
-  [Gherkin]: https://github.com/cucumber/cucumber/wiki/Gherkin
-  [Dredd]: https://github.com/apiaryio/dredd
-  [hooks]: https://dredd.readthedocs.io/en/latest/hooks/
+To use the test suite, first read the docs about [how to create a new hooks handler](http://dredd.org/en/latest/hooks/new-language.html) for Dredd. Implement your hooks handler and then continue with the following guide.
 
-## Usage
-
-### Install the features dependencies
+## Installation
 
-```bash
-npm install -g dredd
-git clone https://github.com/apiaryio/dredd-hooks-template.git
-cd dredd-hooks-template
-bundle install
-```
+1.  Make sure you have [Node.js](https://nodejs.org/) (ideally version 10 or higher) and [npm](https://www.npmjs.com/package/npm) available.
+1.  Create a `package.json` file in the root of your project. This is where your JavaScript dependencies are going to be specified:
 
-### Enable the features for your language
+    ```json
+    {
+      "scripts": { "test": "dredd-hooks-template test" },
+      "private": true
+    }
+    ```
 
-1. Open the feature files in `./features/*.feature`
-1. In all of them, replace:
-  - `{{mylanguage}}` by the hooks handler command for you language
-  - `{{myextension}}` by the extension for your language
-1. Implement the code examples in your language
-1. Run the test suite: `bundle exec cucumber`
+1.  Run `npm install dredd-hooks-template --save-dev` to install and declare this test suite as your development dependency.
+1.  Run `npx dredd-hooks-template init` to get a copy of the test suite in the `./features` directory.
+1.  Open the feature files in `./features/*.feature` and in all of them
 
-### Add the features to your project
+    -   replace `dredd-hooks-{{mylanguage}}` with a path to your hooks handler executable which you want to get tested (e.g. `./bin/dredd_hooks`)
+    -   replace `{{myextension}}` by the extension of the hooks handler language (e.g. `.py`),
+    -   uncomment the code blocks and rewrite them to the hooks handler language.
 
-If the test suite did run as expected, you can now add the features to your project.
-To do so, copy to your project:
+Now you have the test suite ready.
 
-1. the entire `features/` directory
-1. the `Gemfile`, `Gemfile.lock` and `.ruby-version`
+## Usage
 
-Your should now be able to install the features dependencies and run the test suite in your project.
+Every time you run `npx dredd-hooks-template test` (or `npm test`), you should see the test suite running. The end goal is that all the tests pass:
 
-Finally, make `bundle exec cucumber` part of your test suite and CI (see `.travis.example.yml` if you are using [Travis CI][travis]).
+![test suite passing](passing.png)
 
-  [travis]: https://travis-ci.org
+You should add the `package.json` file to Git. When starting from scratch, you can run `npm install` to install the JavaScript dependencies.
 
-## Development
+<a name="upgrading"></a>
 
-The feature files syntax is validated automatically. To perform the validation locally:
+## Upgrading
 
-```bash
-# Install the dependencies
-npm install
+[Watch for newer versions](https://github.com/apiaryio/dredd-hooks-template/releases) of the [dredd-hooks-template package](https://www.npmjs.com/package/dredd-hooks-template) and upgrade regularly to keep up with development of Dredd and the test suite itself. To upgrade, run:
 
-# Run the linter
-npm test
 ```
+$ npx dredd-hooks-template upgrade
+```
+
+It upgrades the package to the latest version and copies the latest feature files to the project's `./features/` directory. It won't overwrite the existing files as the names of the new files get suffixed with version. Then it's up to you to compare the old and new files, spot changes, and update the project's test suite.
+
+## Reference Implementations
+
+The [Python hooks](https://github.com/apiaryio/dredd-hooks-python) and the [Ruby hooks](https://github.com/apiaryio/dredd-hooks-ruby) can be used as examples of how to use this cross-language test suite.
 
-## Examples
+## Keep Tests Running with CI
 
-The [Dredd Hooks Ruby gem][ruby] and the [Dredd Hooks Python package][python] can be used as references to use this cross-language test suite.
+To make sure the hooks handler will always work correctly with Dredd and the expectations won't get accidentally broken, put the tests into [Travis CI](https://travis-ci.org), which runs the tests for each change on your repository. See existing configuration files for inspiration:
 
-  [ruby]: https://github.com/apiaryio/dredd-hooks-ruby
-  [python]: https://github.com/apiaryio/dredd-hooks-python
+- Python: [.travis.yml](https://github.com/apiaryio/dredd-hooks-python/blob/master/.travis.yml)
+- Ruby: [.travis.yml](https://github.com/apiaryio/dredd-hooks-ruby/blob/master/.travis.yml)

cli/copyFeatures.js

@@ -0,0 +1,24 @@
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+
+/**
+ * Copies all '*.feature' files from the 'srcDir' directory to the 'dstDir'
+ * directory, allowing for a transformation of the file basename and
+ * the content on the way using the 'transform()' function
+ */
+module.exports = function copyFeatures(srcDir, dstDir, transform) {
+  glob.sync(path.join(srcDir, '*.feature')).forEach((featureSrcPath) => {
+    const featureSrcContent = fs.readFileSync(featureSrcPath, { encoding: 'utf-8' });
+    const {
+      basename: featureBasename,
+      content: featureContent,
+    } = transform({
+      basename: path.basename(featureSrcPath),
+      content: featureSrcContent,
+    });
+    const featurePath = path.join(dstDir, featureBasename);
+    fs.writeFileSync(featurePath, featureContent, { encoding: 'utf-8' });
+  });
+}

cli/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const run = require('./run');
+const copyFeatures = require('./copyFeatures');
+const replaceDredd = require('./replaceDredd');
+
+
+PROJECT_DIR = process.cwd();
+NODE_MODULES_DIR = path.join(PROJECT_DIR, 'node_modules');
+
+FEATURES_SRC_DIR = path.join(NODE_MODULES_DIR, 'dredd-hooks-template', 'features');
+FEATURES_DIR = path.join(PROJECT_DIR, 'features');
+STEPS_DIR = path.join(FEATURES_SRC_DIR, 'support');
+
+NODE_BIN = process.execPath;
+DREDD_BIN = path.join(NODE_MODULES_DIR, '.bin', 'dredd');
+CUCUMBER_BIN = path.join(NODE_MODULES_DIR, '.bin', 'cucumber-js');
+
+
+function init() {
+  // create a 'features' directory in the project we're initializing
+  fs.mkdirSync(FEATURES_DIR);
+
+  // copy '*.feature' files from the template to the project, process each
+  // file so it references the right Dredd executable
+  copyFeatures(FEATURES_SRC_DIR, FEATURES_DIR, ({ basename, content }) => (
+    {
+      basename,
+      content: replaceDredd(content, DREDD_BIN),
+    }
+  ));
+}
+
+
+function test() {
+  // use cucumber executable installed with the template package and run it
+  // with the 'features' directory in the project (also use steps from
+  // the template package)
+  run(NODE_BIN, [CUCUMBER_BIN, FEATURES_DIR, '--require', STEPS_DIR], { cwd: PROJECT_DIR });
+}
+
+
+function upgrade() {
+  // read the project's package.json and get currently installed version
+  // of the 'dredd-hooks-template' package
+  const packageDataPath = path.join(PROJECT_DIR, 'package.json');
+  const packageData = JSON.parse(fs.readFileSync(packageDataPath, { encoding: 'utf-8' }));
+  const currentVersion = packageData.devDependencies['dredd-hooks-template'];
+
+  // ask npm about the latest published version of the 'dredd-hooks-template'
+  // package
+  const proc = run('npm', ['view', 'dredd-hooks-template', 'version'], { cwd: PROJECT_DIR });
+  const version = proc.stdout.toString().trim();
+
+  // halt in case the project already depends on the latest version
+  if (currentVersion === version) {
+    console.log(`The test suite template is up to date!`);
+    return;
+  }
+
+  // upgrade the package
+  const package = `dredd-hooks-template@${version}`;
+  run('npm', ['install', package, '--save-dev'], { cwd: PROJECT_DIR });
+
+  // copy '*.feature' files from the upgraded 'dredd-hooks-template' package
+  // to the project, but don't overwrite the existing feature files, add these
+  // as new ones, suffixed with the 'dredd-hooks-template' version
+  copyFeatures(FEATURES_SRC_DIR, FEATURES_DIR, ({ basename, content }) => (
+    {
+      basename: `${basename}~${version}`,
+      content: replaceDredd(content, DREDD_BIN),
+    }
+  ));
+}
+
+
+// poor man's CLI implementation (it's just three commands, so not worth
+// a dedicated library)
+if (process.argv.length > 3) {
+  process.exitCode = 1;
+  console.error('Wrong number of arguments');
+} else {
+  const command = process.argv[2];
+  if (command === 'init') {
+    init();
+  } else if (command === 'test') {
+    test();
+  } else if (command === 'upgrade') {
+    upgrade();
+  } else {
+    process.exitCode = 1;
+    console.error('Available commands: init, test, upgrade');
+    console.error('See https://github.com/apiaryio/dredd-hooks-template README')
+  }
+}

cli/replaceDredd.js

@@ -0,0 +1,9 @@
+/**
+ * Replaces mentions of the 'dredd' command in given '*.feature' file
+ * content with a specific path to Dredd executable
+ */
+module.exports = function replaceDredd(text, dreddBin) {
+  return text
+    .replace(/I have "dredd"/g, `I have "${dreddBin}"`)
+    .replace(/I run `dredd /g, `I run \`${dreddBin} `);
+};

cli/run.js

@@ -0,0 +1,13 @@
+const { spawnSync } = require('child_process');
+
+
+/**
+ * Like 'spawnSync()', but prints the stdout/stderr of the subprocess
+ * by default and throws in case the command failed
+ */
+module.exports = function run(command, args, options) {
+  const proc = spawnSync(command, args, { ...options, stdio: 'inherit' });
+  if (proc.error) throw error;
+  if (proc.status) throw new Error(`'${[command].concat(args).join(' ')}' failed`);
+  return proc;
+};