feat(rest): @serenity-js/rest 2.0

affects: @serenity-js/assertions, @serenity-js/core, @serenity-js/cucumber, @serenity-js/rest,
@serenity-js-examples/calculator-app, @serenity-js-examples/cucumber-rest-api-level-testing,
@documentation/esdoc-template, @documentation/website

Completely re-designed version of the REST module

.gitignore

@@ -2,6 +2,9 @@
 .idea
 *.iml
 
+# Serenity BDD
+*.jar
+
 # OS
 .DS_Store
 

documentation/esdoc-template/src/class.html

@@ -16,39 +16,40 @@ <h1 data-ice="name"></h1>
     <span data-ice="instanceDoc"></span>
   </div>
 
+  <div class="description" data-ice="description"></div>
+
   <div class="expression-extends" data-ice="expressionExtends"><h4>Expression Extends:</h4><pre><code data-ice="expressionExtendsCode"></code></pre></div>
   <div class="flat-list" data-ice="mixinExtends"><h4>Mixin Extends:</h4></div>
   <div class="flat-list" data-ice="extendsChain"><h4>Extends:</h4></div>
-  <div class="flat-list" data-ice="directSubclass"><h4>Direct Subclass:</h4></div>
-  <div class="flat-list" data-ice="indirectSubclass"><h4>Indirect Subclass:</h4></div>
+  <div class="flat-list" data-ice="directSubclass"><h4>Direct Subclasses:</h4></div>
+  <div class="flat-list" data-ice="indirectSubclass"><h4>Indirect Subclasses:</h4></div>
   <div class="flat-list" data-ice="implements"><h4>Implements:</h4></div>
   <div class="flat-list" data-ice="indirectImplements"><h4>Indirect Implements:</h4></div>
   <div class="flat-list" data-ice="directImplemented"><h4>Direct Implemented:</h4></div>
   <div class="flat-list" data-ice="indirectImplemented"><h4>Indirect Implemented:</h4></div>
 
   <div class="deprecated" data-ice="deprecated"></div>
   <div class="experimental" data-ice="experimental"></div>
-  <div class="description" data-ice="description"></div>
   <div class="decorator" data-ice="decorator"><h4>Decorators:</h4></div>
 
-  <div data-ice="see"><h4>See:</h4></div>
-
   <div data-ice="exampleDocs">
-    <h4>Example:</h4>
+    <h4 id="examples">Examples:</h4>
     <div class="example-doc" data-ice="exampleDoc">
       <div class="example-caption" data-ice="exampleCaption"></div>
       <pre class="source-code"><code data-ice="exampleCode"></code></pre>
     </div>
   </div>
 
   <div data-ice="tests">
-    <h4>Test:</h4>
+    <h4 id="tests">Tests:</h4>
     <ul>
       <li data-ice="test"></li>
     </ul>
   </div>
 
   <div data-ice="todo"><h4>TODO:</h4></div>
+
+  <div data-ice="see"><h4>See also:</h4></div>
 </div>
 
 <div data-ice="staticMemberSummary"><h2>Static Member Summary</h2></div>

documentation/esdoc-template/src/details.html

@@ -25,7 +25,7 @@ <h3 data-ice="anchor">
   <div data-ice="properties"></div>
 
   <div class="return-params" data-ice="returnParams">
-    <h4>Return:</h4>
+    <h4>Returns:</h4>
     <table>
       <tbody>
         <tr>
@@ -38,7 +38,7 @@ <h4>Return:</h4>
   </div>
 
   <div data-ice="emitWrap">
-    <h4>Emit:</h4>
+    <h4>Emits:</h4>
     <table>
       <tbody>
       <tr class="emit" data-ice="emit">
@@ -50,7 +50,7 @@ <h4>Emit:</h4>
   </div>
 
   <div data-ice="listenWrap">
-    <h4>Listen:</h4>
+    <h4>Listens:</h4>
     <table>
       <tbody>
       <tr class="listen" data-ice="listen">
@@ -62,7 +62,7 @@ <h4>Listen:</h4>
   </div>
 
   <div data-ice="throwWrap">
-    <h4>Throw:</h4>
+    <h4>Throws:</h4>
     <table>
       <tbody>
       <tr class="throw" data-ice="throw">
@@ -76,15 +76,15 @@ <h4>Throw:</h4>
   <div data-ice="decorator"><h4>Decorators:</h4></div>
 
   <div data-ice="example">
-    <h4>Example:</h4>
+    <h4 id="examples">Examples:</h4>
     <div class="example-doc" data-ice="exampleDoc">
       <div class="example-caption" data-ice="exampleCaption"></div>
       <pre class="source-code"><code data-ice="exampleCode"></code></pre>
     </div>
   </div>
 
   <div data-ice="tests">
-    <h4>Test:</h4>
+    <h4>Tests:</h4>
     <ul>
       <li data-ice="test"></li>
     </ul>

documentation/website/build.js

@@ -22,7 +22,7 @@ const
     browserSync      = devMode ? require('metalsmith-browser-sync') : noop,
     highlight        = require('highlight.js'),
 
-    highlightedLanguages = ['typescript', 'javascript', 'json'];
+    highlightedLanguages = ['typescript', 'javascript', 'json', 'gherkin'];
 
 Metalsmith(__dirname)
     .source('src')

documentation/website/package.json

@@ -39,6 +39,7 @@
     "@serenity-js/assertions": "*",
     "@serenity-js/core": "*",
     "@serenity-js/cucumber": "*",
+    "@serenity-js/rest": "*",
     "cheerio": "1.0.0-rc.2",
     "clean-css": "4.2.1",
     "glob": "7.1.3",

documentation/website/plugins/highlighEsdoc.js

@@ -1,13 +1,13 @@
 'use strict';
-
+const fs = require('fs');
 const cheerio = require('cheerio');
 
+let i = 0;
+
 module.exports = function highlightEsdoc(highlight, languages) {
 
     return function(files, ms, done) {
 
-        setImmediate(done);
-
         Object.keys(files).filter(path => /\.html$/.test(path)).forEach(path => {
             const $ = cheerio.load(files[path].contents.toString('utf8'));
 
@@ -16,12 +16,18 @@ module.exports = function highlightEsdoc(highlight, languages) {
 
                 const result = highlight.highlightAuto(el.text(), languages);
 
+                if (! result.language) {
+                    return done(new Error(`Could not detect the language of the following code sample: ${result.value}`));
+                }
+
                 el.html(result.value);
                 el.addClass('hljs');
                 el.addClass(result.language);
             });
 
             files[path].contents = Buffer.from($.html());
         });
+
+        return done();
     };
 }

documentation/website/src/guides/screenplay-pattern.md

@@ -82,7 +82,7 @@ expect(james.toSee(TodoListItems.Displayed)).eventually.equal([ 'Buy some milk'
 
 The Goal of an Actor is represented by the subject of the scenario:
 
-``` gherkin
+```gherkin
 Scenario: Adding the first todo item
 ```
 

examples/calculator-app/index.js

@@ -0,0 +1,24 @@
+const
+    port = process.env.PORT || 3000,
+    runningInDevMode = `${ process.env.NODE_ENV }`.toLocaleLowerCase() === 'test';
+
+(runningInDevMode ? inMemoryServer() : compiledServer())
+    .use(require('morgan')('combined'))
+    .listen(port, () => console.log(`Calculator server started on port ${ port }`));
+
+// ---
+
+function inMemoryServer() {
+    require('ts-node/register');
+    return require('./src/rest-api');
+}
+
+function compiledServer() {
+    try {
+        return require('./lib/rest-api');
+    }
+    catch(e) {
+        console.error('Remember to compile the module before trying to start the server: npm run compile');
+        process.exit(1);
+    }
+}

examples/calculator-app/nodemon.json

@@ -0,0 +1,10 @@
+{
+  "ignore": [
+    "spec/**/*.ts",
+    "node_modules"
+  ],
+  "watch": [
+    "src"
+  ],
+  "ext": "ts"
+}