feat(cucumber): @serenity-js/cucumber adapter re-write

affects: @serenity-js/core, @serenity-js/cucumber, @integration/cucumber, @integration/testing-tools

The new version will make it possible to support scenario outlines (#168, #220) and provide
additional context in the report

Makefile

@@ -0,0 +1,19 @@
+default: clean compile
+
+clean:
+	npm run clean
+
+lint:
+	npm run lint
+
+test:
+	npm test
+
+compile:
+	npm run compile
+
+integration-test:
+	npm run integration-test
+
+verify:
+	npm run verify

integration/cucumber/.gitignore

@@ -0,0 +1,7 @@
+# Node
+node_modules
+*.log
+
+# Build artifacts
+.nyc_output
+lib

integration/cucumber/features/passing_scenario.feature

@@ -0,0 +1,11 @@
+Feature: Serenity/JS recognises a passing scenario
+
+  In order to correctly report the outcome of a scenario
+  Serenity/JS should recognise when a scenario passes
+
+  Scenario: A passing scenario
+
+    A scenario where all the steps pass
+
+    Given a step that passes
+

integration/cucumber/features/step_definitions/README.md

@@ -0,0 +1,2 @@
+# Notes
+- [Cucumber.js step definitions](https://github.com/cucumber/cucumber-js/blob/509e64fd5d9835c9101b33a642e6ccac459025b8/docs/support_files/step_definitions.md)

integration/cucumber/features/step_definitions/callback.steps.ts

@@ -0,0 +1,33 @@
+import { TableDefinition } from 'cucumber';
+
+type Callback =  (error?: Error, pending?: string) => void;
+
+export = function() {
+    this.Given(/^.*step (?:.*) passes$/, function(done: Callback) {
+        done();
+    });
+
+    this.Given(/^.*step (?:.*) fails$/, function(done: Callback) {
+        done(new Error(`Something's wrong`));
+    });
+
+    this.Given(/^.*step (?:.*) explicitly pending$/, function(done: Callback) {
+        done(void 0, 'pending');
+    });
+
+    this.Given(/^.*step (?:.*) explicitly skipped/, function(done: Callback) {
+        done(void 0, 'skipped');
+    });
+
+    this.Given(/^.*step (?:.*) receives a table:$/, function(data: TableDefinition, done) {
+        done();
+    });
+
+    this.Given(/^.*step (?:.*) receives a doc string:$/, function(docstring: string, done) {
+        done();
+    });
+
+    this.Given(/^.*step times out$/,  { timeout: 100 }, function(done: Callback) {
+        setTimeout(done, 1000);
+    });
+};

integration/cucumber/features/step_definitions/promise.steps.ts

@@ -0,0 +1,33 @@
+import { TableDefinition } from 'cucumber';
+
+export = function() {
+    this.Given(/^.*step (?:.*) passes$/, function() {
+        return Promise.resolve();
+    });
+
+    this.Given(/^.*step (?:.*) fails$/, function() {
+        return Promise.reject(new Error(`Something's wrong`));
+    });
+
+    this.Given(/^.*step (?:.*) explicitly pending$/, function() {
+        return Promise.resolve('pending');
+    });
+
+    this.Given(/^.*step (?:.*) explicitly skipped/, function() {
+        return Promise.resolve('skipped');
+    });
+
+    this.Given(/^.*step (?:.*) receives a table:$/, function(data: TableDefinition, done) {
+        return Promise.resolve();
+    });
+
+    this.Given(/^.*step (?:.*) receives a doc string:$/, function(docstring: string, done) {
+        return Promise.resolve();
+    });
+
+    this.Given(/^.*step times out$/,  { timeout: 100 }, function() {
+        return new Promise((resolve, reject) => {
+            setTimeout(resolve, 1000);
+        });
+    });
+};

integration/cucumber/features/step_definitions/synchronous.steps.ts

@@ -0,0 +1,31 @@
+import { TableDefinition } from 'cucumber';
+
+export = function() {
+    this.Given(/^.*step (?:.*) passes$/, function() {
+        return void 0;
+    });
+
+    this.Given(/^.*step (?:.*) fails$/, function() {
+        throw new Error(`Something's wrong`);
+    });
+
+    this.Given(/^.*step (?:.*) explicitly pending$/, function() {
+        return 'pending';
+    });
+
+    this.Given(/^.*step (?:.*) explicitly skipped/, function() {
+        return 'skipped';
+    });
+
+    this.Given(/^.*step (?:.*) receives a table:$/, function(data: TableDefinition) {
+        return void 0;
+    });
+
+    this.Given(/^.*step (?:.*) receives a doc string:$/, function(docstring: string) {
+        return void 0;
+    });
+
+    this.Given(/^.*step times out$/,  { timeout: 100 }, function(done: (error: Error, pending: string) => void) {
+        setTimeout(done, 1000);
+    });
+};

integration/cucumber/features/support/after_hook.ts

@@ -0,0 +1,6 @@
+module.exports = function() {
+
+    this.After(() => {
+        // no-op
+    });
+};

integration/cucumber/features/support/before_hook.ts

@@ -0,0 +1,6 @@
+module.exports = function() {
+
+    this.Before(() => {
+        // no-op
+    });
+};

integration/cucumber/features/support/configure_serenity.ts

@@ -0,0 +1,13 @@
+import { ChildProcessReporter } from '@integration/testing-tools';
+import { serenity } from '@serenity-js/core';
+import { DebugReporter } from '@serenity-js/core/lib/stage';
+
+module.exports = function() {
+
+    this.setDefaultTimeout(5000);
+
+    serenity.stageManager.register(
+        new ChildProcessReporter(),
+        new DebugReporter(),
+    );
+};

integration/cucumber/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@integration/cucumber",
+  "version": "0.0.0",
+  "description": "Cucumber JS integration tests",
+  "author": {
+    "name" : "Jan Molak",
+    "email" : "jan.molak@smartcodeltd.co.uk",
+    "url" : "https://janmolak.com"
+  },
+  "homepage": "http://serenity-js.org",
+  "license": "Apache-2.0",
+  "private": true,
+  "config": {
+    "access": "private"
+  },
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "scripts": {
+    "clean": "rimraf lib",
+    "lint": "tslint --project tsconfig.json --config ../../tslint.json --format stylish",
+    "test": "mocha --opts ../../mocha.opts 'spec/**/*.spec.*'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jan-molak/serenity-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jan-molak/serenity-js/issues"
+  },
+  "engines": {
+    "node": ">= 6.9.x",
+    "npm": ">= 3"
+  },
+  "devDependencies": {
+    "@integration/testing-tools": "*",
+    "@serenity-js/core": "*",
+    "@serenity-js/cucumber": "*",
+    "@types/cucumber": "1.3.3",
+    "cucumber": "1.3.3",
+    "mocha": "5.2.0",
+    "mocha-testdata": "1.2.0"
+  }
+}

integration/cucumber/spec/recognises_passing_scenario.spec.ts

@@ -0,0 +1,59 @@
+import { expect, ifExitCodeIsOtherThan, logOutput } from '@integration/testing-tools';
+import { ActivityFinished, ActivityStarts, SceneFinished, SceneStarts, SceneTagged, TestRunnerDetected } from '@serenity-js/core/lib/events';
+import { ExecutionSuccessful, FeatureTag, Name } from '@serenity-js/core/lib/model';
+
+import 'mocha';
+import { given } from 'mocha-testdata';
+
+import { cucumber } from '../src';
+
+describe('@serenity-js/cucumber', function() {
+
+    this.timeout(5000);
+
+    given([
+        'synchronous',
+        'promise',
+        'callback',
+    ]).
+    it('recognises a passing scenario', (stepInterface: string) =>
+        cucumber(
+            '--require', 'features/support/configure_serenity.ts',
+            // '--require', 'features/support/before_hook.ts',
+            // '--require', 'features/support/after_hook.ts',
+            '--require', `features/step_definitions/${ stepInterface }.steps.ts`,
+            '--require', 'node_modules/@serenity-js/cucumber/register.js',
+            'features/passing_scenario.feature',
+        ).
+        then(ifExitCodeIsOtherThan(0, logOutput)).
+        then(res => {
+            expect(res.exitCode).to.equal(0);
+
+            expect(res.events).to.have.lengthOf(6);
+
+            expect(res.events[0]).to.be.instanceOf(SceneStarts)
+                .and.have.property('value')
+                .that.has.property('name')
+                .equal(new Name('A passing scenario'));
+
+            expect(res.events[1]).to.be.instanceOf(TestRunnerDetected)
+                .and.have.property('value').equal(new Name('Cucumber'));
+
+            expect(res.events[2]).to.be.instanceOf(SceneTagged)
+                .and.have.property('tag')
+                .equal(new FeatureTag('Serenity/JS recognises a passing scenario'));
+
+            expect(res.events[3]).to.be.instanceOf(ActivityStarts)
+                .and.have.property('value')
+                .that.has.property('name')
+                .equal(new Name('Given a step that passes'));
+
+            expect(res.events[4]).to.be.instanceOf(ActivityFinished)
+                .and.have.property('outcome')
+                .equal(new ExecutionSuccessful());
+
+            expect(res.events[5]).to.be.instanceOf(SceneFinished)
+                .and.have.property('outcome')
+                .equal(new ExecutionSuccessful());
+        }));
+});

integration/cucumber/src/cucumber.ts

@@ -0,0 +1,19 @@
+import { spawner, SpawnResult } from '@integration/testing-tools';
+import * as path from 'path';
+
+const cucumberExecutable = path.resolve(
+    require.resolve('cucumber/package.json'),
+    '..',
+    'bin',
+    'cucumber.js',
+);
+
+const cucumberSpawner = spawner(
+    cucumberExecutable,
+    { cwd: path.resolve(__dirname, '..') },
+);
+
+export const cucumber = (...params: string[]): Promise<SpawnResult> => cucumberSpawner(
+    '--compiler', 'ts:ts-node/register',
+    ...params,
+);

integration/cucumber/src/index.ts

@@ -0,0 +1 @@
+export * from './cucumber';

integration/cucumber/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": [ "es5", "es6" ],
+    "module": "commonjs",
+    "sourceMap": true,
+    "declaration": true
+  },
+
+  "exclude": [
+    "node_modules"
+  ]
+}

integration/testing-tools/.gitignore

@@ -0,0 +1,7 @@
+# Node
+node_modules
+*.log
+
+# Build artifacts
+.nyc_output
+lib

integration/testing-tools/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@integration/testing-tools",
+  "version": "0.0.0",
+  "description": "Internal module to help test integration of Serenity/JS with test runners and frameworks",
+  "author": {
+    "name" : "Jan Molak",
+    "email" : "jan.molak@smartcodeltd.co.uk",
+    "url" : "https://janmolak.com"
+  },
+  "homepage": "http://serenity-js.org",
+  "license": "Apache-2.0",
+  "private": true,
+  "config": {
+    "access": "private"
+  },
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "keywords": [
+    "serenity-js",
+    "internal"
+  ],
+  "scripts": {
+    "clean": "rimraf lib",
+    "lint": "tslint --project tsconfig.json --config ../../tslint.json --format stylish",
+    "compile": "tsc --project tsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jan-molak/serenity-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jan-molak/serenity-js/issues"
+  },
+  "engines": {
+    "node": ">= 6.9.x",
+    "npm": ">= 3"
+  },
+  "peerDependencies": {
+    "@serenity-js/core": "*"
+  },
+  "devDependencies": {
+    "@serenity-js/core": "*"
+  },
+  "dependencies": {
+    "chai": "4.1.2",
+    "chai-as-promised": "7.1.1",
+    "tiny-types": "1.10.3"
+  }
+}

integration/testing-tools/src/child-process-reporter/ChildProcessReporter.ts

@@ -0,0 +1,24 @@
+import { DomainEvent } from '@serenity-js/core/lib/events';
+import { StageCrewMember, StageManager } from '@serenity-js/core/lib/stage';
+import { Serialised } from 'tiny-types';
+import { DTO } from './DTO';
+
+export class ChildProcessReporter implements StageCrewMember {
+    private stageManager: StageManager;
+
+    assignTo(stageManager: StageManager) {
+        this.stageManager = stageManager;
+        this.stageManager.register(this);
+    }
+
+    notifyOf(event: DomainEvent): void {
+        process.send(this.serialised(event));
+    }
+
+    private serialised(event: DomainEvent): DTO<DomainEvent> {
+        return ({
+            type:  event.constructor.name,
+            value: event.toJSON() as Serialised<DomainEvent>,
+        });
+    }
+}