#13 add screenAnnotation support. Fix status "skipped" for useCases w…

…ith all scenarios skipped

example/protractor.conf.js

@@ -31,7 +31,8 @@ var exportsConfig = {
   onPrepare: function () {
     // enable scenarioo userDocumentation (see more on http://www.scenarioo.org)
     // pass in the current branch of your VCS you are testing, an arbitrary build name and the current revision you are testing.
-    var scenariooReporter = require('../lib/scenarioo-js').reporter({
+    var scenarioo = require('../lib/scenarioo-js');
+    var scenariooReporter = scenarioo.reporter({
       targetDirectory: './scenariodocu',
       branchName: 'master',
       branchDescription: 'the master branch',
@@ -44,12 +45,12 @@ var exportsConfig = {
     jasmine.getEnv().addReporter(scenariooReporter);
 
 
-
     // this demonstrates how to include your own dsl ("describeScenario", "describeUseCase")
     // you do not need this in a basic setup.
     require('./test/customDsl');
     require('./test/customExtendedDsl');
     require('./test/chainedDsl');
+
   },
 
   params: {

example/test/sampleSpec.js

@@ -1,12 +1,12 @@
 var scenarioo = require('../../lib/scenarioo-js');
 
+
 /**
  *  This defines a scenarioo "Use Case". It can contain multiple "scenarios".
  *  Scenarioo will generate the appropriate report files (xml) for this use case.
  */
 describe('Example Usecase', function exampleUseCase() {
 
-
   /**
    * This defines a scenarioo "scenario".
    * Scenarioo will generate the appropriate report files (xml) for this scenario.
@@ -16,39 +16,34 @@ describe('Example Usecase', function exampleUseCase() {
     // write your normal webdriverjs / protractor test-code here
 
     browser.get('/index.html');
-
     // use scenarioo's docuWriter to save step information (screenshot, etc.)
     scenarioo.saveStep('start');
 
     element(by.css('li#item_one')).click();
-    expect(element(by.id('selected')).getText('one'));
-    scenarioo.saveStep('one is displayed', {
-      customInfo: 'This is my custom information that I gathered during test-run.',
-      moreCustomInfo: 'It will be displayed as metadata for this step!'
-    });
+    expect(element(by.id('selected')).getText()).toEqual('one');
+    scenarioo.saveStep('one is displayed');
 
     element(by.css('li#item_two')).click();
-    expect(element(by.id('selected')).getText('two'));
-    scenarioo.saveStep('two is displayed', {
-      complexCustomInfo: [
-        'this is a more complex example of metadata',
-        'We expect this to end up in valid "entry/key/value" xml'
-      ],
-      moreComplexCustomInfo: [
-        {
-          attributeOne: 'valueOne',
-          attributeTwo: 'valueTwo'
-        },
-        {
-          attributeOne: 'valueOneOne',
-          attributeTwo: 'valueTwoTwo'
-        }
-      ]
-    });
+    expect(element(by.id('selected')).getText()).toEqual('two');
+    scenarioo.saveStep('two is displayed');
 
     element(by.css('li#item_three')).click();
-    expect(element(by.id('selected')).getText('three'));
-    scenarioo.saveStep('three is displayed');
+    expect(element(by.id('selected')).getText()).toEqual('three');
+    scenarioo.saveStep('three is displayed', {
+      screenAnnotations: [{
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+        style: 'CLICK',
+        clickAction: 'TO_NEXT_STEP'
+      }]
+    });
+
+  });
+
+
+  xit('Skipped Scenario', function () {
 
   });
 

lib/docuWriter/docuWriter.js

@@ -79,6 +79,15 @@ function writeStepXml(stepName, currentScenario, absScenarioPath, additionalProp
       if (additionalProperties && additionalProperties.labels) {
         stepData.stepDescription.labels = additionalProperties.labels;
       }
+      if (additionalProperties && additionalProperties.screenAnnotations && _.isArray(additionalProperties.screenAnnotations)) {
+        stepData.screenAnnotations = additionalProperties.screenAnnotations.map(function (annotation) {
+          return _.merge({},
+            _.omit(annotation, ['x', 'y', 'width', 'height']),
+            {
+              region: _.pick(annotation, ['x', 'y', 'width', 'height'])
+            });
+        });
+      }
 
       var xmlFileName = path.join(absScenarioPath, 'steps', currentStepCounter + '.xml');
 
@@ -198,13 +207,19 @@ var docuWriter = {
    * To be invoked in your e2e tests.
    *
    * @func docuWriter#saveStep
-   * @param {string} stepName
+   * @param {string} [stepName]
    * @param {object} [additionalProperties]
    * @param {string[]} [additionalProperties.labels]
    * @param {object} [additionalProperties.details]
+   * @param {object[]} [additionalProperties.screenAnnotations]
    * @returns {Promise} The returned promise will resolve to an object containing the saved step object, the path to the step xml file as well as the path to the screenshot file
    */
   saveStep: function (stepName, additionalProperties) {
+    if (!_.isString(stepName)) {
+      additionalProperties = stepName;
+      stepName = '';
+    }
+
     // Because this is invoked by the e2e test,
     // we have to access the store directly from here.
 

lib/docuWriter/validationSchemas/scenario.json

@@ -10,7 +10,8 @@
     "status": {
       "enum": [
         "success",
-        "failed"
+        "failed",
+        "skipped"
       ]
     },
     "labels": {
@@ -25,4 +26,4 @@
     "status"
   ],
   "additionalProperties": false
-}
+}

lib/docuWriter/validationSchemas/step.json

@@ -52,6 +52,67 @@
       },
       "additionalProperties": false
     },
+    "screenAnnotations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "region": {
+            "type": "object",
+            "properties": {
+              "x": {
+                "type": "integer"
+              },
+              "y": {
+                "type": "integer"
+              },
+              "width": {
+                "type": "integer"
+              },
+              "height": {
+                "type": "integer"
+              }
+            },
+            "additionalProperties": false
+          },
+          "style": {
+            "enum": [
+              "CLICK",
+              "KEYBOARD",
+              "EXPECTED",
+              "NAVIGATE_TO_URL",
+              "ERROR",
+              "WARN",
+              "INFO",
+              "HIGHLIGHT",
+              "DEFAULT"
+            ]
+          },
+          "screenText": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "clickAction": {
+            "enum": [
+              "TO_NEXT_STEP",
+              "TO_URL"
+            ]
+          },
+          "clickActionUrl": {
+            "type": "string"
+          },
+          "clickActionText": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "metadata": {
       "type": "object",
       "properties": {

lib/docuWriter/validationSchemas/useCase.json

@@ -10,7 +10,8 @@
     "status": {
       "enum": [
         "success",
-        "failed"
+        "failed",
+        "skipped"
       ]
     },
     "labels": {
@@ -25,4 +26,4 @@
     "status"
   ],
   "additionalProperties": false
-}
+}

lib/docuWriter/xmlWriter.js

@@ -34,7 +34,8 @@ function serialize(rootElement, data) {
 
     // we want the array property "labels" to be represented as <labels><label>....</label></labels>
     arrayMap: {
-      labels: 'label'
+      labels: 'label',
+      screenAnnotations: 'screenAnnotation'
     }
   });
 }

lib/reporters/jasmine.js

@@ -87,7 +87,7 @@ function jasmineStatusToScenariooStatus(jasmineStatus) {
   var map = {
     pending: scenariooReporter.SKIPPED,
     disabled: scenariooReporter.SKIPPED,
-    passed: scenariooReporter.SUCCESSFUL,
+    passed: scenariooReporter.SUCCESS,
     failed: scenariooReporter.FAILED
   };
   var mapped = map[jasmineStatus];

lib/scenarioo-js.js

@@ -47,7 +47,7 @@ var scenariooJs = {
    * Allows you to set additional information like "description" and "labels"
    *
    * @func scenarioo#getUseCaseContext
-   * @returns {Context}
+   * @returns {context}
    */
   getUseCaseContext: function () {
     return contextFactory('useCase');
@@ -58,7 +58,7 @@ var scenariooJs = {
    * Allows you to set additional information like "description" and "labels"
    *
    * @func scenarioo#getScenarioContext
-   * @returns {Context}
+   * @returns {context}
    */
   getScenarioContext: function () {
     return contextFactory('scenario');
@@ -68,13 +68,22 @@ var scenariooJs = {
    * Call this in your e2e test functions whenever you want scenarioo to report a step (with screen shot and metadata, etc.)
    *
    * @func scenarioo#saveStep
-   * @param {string} stepName
+   * @param {string} [stepName]
    * @param {object} [additionalProperties]
    * @param {string[]} [additionalProperties.labels]
    * @param {object} [additionalProperties.details]
+   * @param {object[]} [additionalProperties.screenAnnotations]
    * @returns {Promise} The returned promise will resolve to an object containing the saved step object, the path to the step xml file as well as the path to the screenshot file
    */
-  saveStep: docuWriter.saveStep.bind(docuWriter)
+  saveStep: function () {
+    // make sure that "scenarioo.saveStep()" gets added to the protractor controlFlow
+    // this ensures that the save operation is not invoked immediately, but in-sync with the flow.
+    // We do this wrapping here in order to keep docuWriter simple (not another dependency to protractor)
+    var stepArguments = arguments;
+    browser.controlFlow().execute(function () {
+      docuWriter.saveStep.apply(docuWriter, stepArguments);
+    });
+  }
 
 };