#304: update sakuli-api docs

ConSol · Apr 22, 2018 · d039b44 · d039b44
1 parent 76d0b84
commit d039b44
Show file tree

Hide file tree

Showing 6 changed files with 56 additions and 28 deletions.
diff --git a/docs/manual/testdefinition/sakuli-api-application.adoc b/docs/manual/testdefinition/sakuli-api-application.adoc
@@ -12,7 +12,7 @@ Application Class - Represents an application.
 
 *Params*
 
-* applicationNameOrPath `String` - Path to the application file. *Example:* `C:\Windows\system32\notepad.exe`
+* applicationNameOrPath `String` - Path to the application file. Example: `C:\Windows\system32\notepad.exe`
 * optResumeOnException `Boolean` - Determines whether to ignore exceptions from this class. If this parameter is
 undefined, it will be false.
 

diff --git a/docs/manual/testdefinition/sakuli-api-environment.adoc b/docs/manual/testdefinition/sakuli-api-environment.adoc
@@ -107,7 +107,7 @@ Takes a screenshot of the current screen and add the current timestamp in the fi
 * optFormat `string` - optional format, for the screenshot (currently supported: jpg and png)
  If null or empty use property `sakuli.screenshot.format`
 
-*Returns*: `String` - file path to the created screenshot OR null on errors
+*Returns*: `Path` - to the created screenshot OR null on errors
 *Example*
 [source,js]
 ----

diff --git a/docs/manual/testdefinition/sakuli-api-testcase.adoc b/docs/manual/testdefinition/sakuli-api-testcase.adoc
@@ -12,9 +12,10 @@ TestCase - initializes the Sakuli object and sets the warning and critical time
 
 *Params*
 
-* warningTime `number` - threshold in seconds. If the threshold is set to 0,
+* optCaseId `String` - optional ID to set the testcase ID to some specifc value. Default is the folder name.
+* optWarningTime `number` - threshold in seconds. If the threshold is not set or is set to 0,
  the execution time will never exceed, so the state will be always OK!
-* criticalTime `number` - threshold in seconds. If the threshold is set to 0,
+* optCriticalTime `number` - threshold in seconds. If the threshold is not set or is set to 0,
  the execution time will never exceed, so the state will be always OK!
 * optImagePathArray `Array.&lt;String&gt;` - (optional) Path or Array of Paths to the folder containing the image patterns
  for these test cases.
@@ -23,16 +24,20 @@ TestCase - initializes the Sakuli object and sets the warning and critical time
 *Example*
 [source,js]
 ----
-var testCase = new TestCase(20,30, "path-to/image-folder-name");
+//new syntex since v1.2.0
+var testCase = new TestCase(["own-case-id", 20, 30, "path-to/image-folder-name"]);
+
+//old syntax &lt; v1.2.0
+var testCase = new TestCase(20, 30, ["path-to/image-folder-name"]);
 ----
 
 *Members*
 
 * link:#TestCase[TestCase]
 * link:#TestCase.addImagePaths[TestCase.addImagePaths(imagePaths)]
-* link:#TestCase.endOfStep[TestCase.endOfStep(stepName, optWarningTime)]
+* link:#TestCase.endOfStep[TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)]
 * link:#TestCase.handleException[TestCase.handleException(e)]
-* link:#TestCase.saveResult[TestCase.saveResult()]
+* link:#TestCase.saveResult[TestCase.saveResult(optForward)]
 * link:#TestCase.getID[TestCase.getID()]
 * link:#TestCase.getLastURL[TestCase.getLastURL()]
 * link:#TestCase.getTestCaseFolderPath[TestCase.getTestCaseFolderPath()]
@@ -52,7 +57,7 @@ If a relative path is assigned, the current testcase folder will be used as curr
 
 
 [[TestCase.endOfStep]]
-.TestCase.endOfStep(stepName, optWarningTime)
+.TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)
 
 A step allows to sub-divide a case to measure logical units, such as "login", "load report" etc. in its
 particular runtime. When a case starts, Sakuli starts a "step" timer. It gets read out, stored with the
@@ -65,6 +70,11 @@ If the step runtime exceeds the step threshold (second parameter, optional), the
 * stepName `String`
 * optWarningTime `number` - (optional) threshold in seconds, default = 0. If the threshold is set to 0,
  the execution time will never exceed, so the state will be always OK!
+* optCriticalTime `number` - (optional) threshold in seconds, default = 0. If the threshold is set to 0,
+ the execution time will never exceed, so the state will be always OK!
+* optForward `boolean` - (optional) indicate whether the result of the test step shall be immediately
+ processed by the enabled forwarders. This means before the test suite has been executed to
+ the end. If not specified in another way, this option is disabled! Default: `false`
 
 
 [[TestCase.handleException]]
@@ -97,6 +107,10 @@ Saves the results of the current test case for further processing.
 
 Should be called in finally-block of the test case:
 
+*Params*
+
+* optForward `boolean` - indicate whether the result of the test case shall be immediately processed by the enabled forwarders. This means before the test suite has been executed to the end. If not specified in another way, this option is disabled! Default: `false`
+
 *Example*
 [source,js]
 ----

diff --git a/docs/manual/testdefinition/sakuli-api.adoc b/docs/manual/testdefinition/sakuli-api.adoc
@@ -26,9 +26,9 @@ IMPORTANT: All classes and methods are implemented identical for Java and JavaSc
 * link:#Sahi-API[Sahi-API]
 * link:#TestCase[TestCase]
 ** link:#TestCase.addImagePaths[TestCase.addImagePaths(imagePaths)]
-** link:#TestCase.endOfStep[TestCase.endOfStep(stepName, optWarningTime)]
+** link:#TestCase.endOfStep[TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)]
 ** link:#TestCase.handleException[TestCase.handleException(e)]
-** link:#TestCase.saveResult[TestCase.saveResult()]
+** link:#TestCase.saveResult[TestCase.saveResult(optForward)]
 ** link:#TestCase.getID[TestCase.getID()]
 ** link:#TestCase.getLastURL[TestCase.getLastURL()]
 ** link:#TestCase.getTestCaseFolderPath[TestCase.getTestCaseFolderPath()]

diff --git a/docs/manual/testdefinition/sakuli-api.md b/docs/manual/testdefinition/sakuli-api.md
@@ -5,9 +5,9 @@
 * [Sahi-API](#Sahi-API)
 * [TestCase](#TestCase)
   * [TestCase.addImagePaths(imagePaths)](#TestCase.addImagePaths)
-  * [TestCase.endOfStep(stepName, optWarningTime)](#TestCase.endOfStep)
+  * [TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)](#TestCase.endOfStep)
   * [TestCase.handleException(e)](#TestCase.handleException)
-  * [TestCase.saveResult()](#TestCase.saveResult)
+  * [TestCase.saveResult(optForward)](#TestCase.saveResult)
   * [TestCase.getID()](#TestCase.getID)
   * [TestCase.getLastURL()](#TestCase.getLastURL)
   * [TestCase.getTestCaseFolderPath()](#TestCase.getTestCaseFolderPath)
@@ -123,26 +123,31 @@ TestCase - initializes the Sakuli object and sets the warning and critical time
 
 **Params**
 
-- warningTime `number` - threshold in seconds. If the threshold is set to 0,
+- optCaseId `String` - optional ID to set the testcase ID to some specifc value. Default is the folder name.  
+- optWarningTime `number` - threshold in seconds. If the threshold is not set or is set to 0,
                 the execution time will never exceed, so the state will be always OK!  
-- criticalTime `number` - threshold in seconds. If the threshold is set to 0,
+- optCriticalTime `number` - threshold in seconds. If the threshold is not set or is set to 0,
                 the execution time will never exceed, so the state will be always OK!  
 - optImagePathArray `Array.<String>` - (optional) Path or Array of Paths to the folder containing the image patterns
                                     for these test cases.  
 
 **Returns**:  - an initialized Sakuli object.  
 **Example**  
 ```
-var testCase = new TestCase(20,30, "path-to/image-folder-name");
+//new syntex since v1.2.0
+var testCase = new TestCase(["own-case-id", 20, 30, "path-to/image-folder-name"]);
+
+//old syntax < v1.2.0
+var testCase = new TestCase(20, 30, ["path-to/image-folder-name"]);
 ```
 
 **Members**
 
 * [TestCase](#TestCase)
   * [TestCase.addImagePaths(imagePaths)](#TestCase.addImagePaths)
-  * [TestCase.endOfStep(stepName, optWarningTime)](#TestCase.endOfStep)
+  * [TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)](#TestCase.endOfStep)
   * [TestCase.handleException(e)](#TestCase.handleException)
-  * [TestCase.saveResult()](#TestCase.saveResult)
+  * [TestCase.saveResult(optForward)](#TestCase.saveResult)
   * [TestCase.getID()](#TestCase.getID)
   * [TestCase.getLastURL()](#TestCase.getLastURL)
   * [TestCase.getTestCaseFolderPath()](#TestCase.getTestCaseFolderPath)
@@ -159,18 +164,23 @@ If a relative path is assigned, the current testcase folder will be used as curr
 - imagePaths `string` - one or more path strings  
 
 <a name="TestCase.endOfStep"></a>
-##TestCase.endOfStep(stepName, optWarningTime)
+##TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)
 A step allows to sub-divide a case to measure logical units, such as "login", "load report" etc. in its
 particular runtime. When a case starts, Sakuli starts a "step" timer. It gets read out, stored with the
 step name, and the timer will set to `0` each time endOfStep() is called.
-If the step runtime exceeds the step threshold (second parameter, optional), the step is saved with state 
+If the step runtime exceeds the step threshold (second parameter, optional), the step is saved with state
 "WARNING" (there is no CRITICAL state).
 
 **Params**
 
 - stepName `String`  
 - optWarningTime `number` - (optional) threshold in seconds, default = 0. If the threshold is set to 0,
                 the execution time will never exceed, so the state will be always OK!  
+- optCriticalTime `number` - (optional) threshold in seconds, default = 0. If the threshold is set to 0,
+                the execution time will never exceed, so the state will be always OK!  
+- optForward `boolean` - (optional) indicate whether the result of the test step shall be immediately
+                 processed by the enabled forwarders. This means before the test suite has been executed to
+                 the end. If not specified in another way, this option is disabled! Default: `false`  
 
 <a name="TestCase.handleException"></a>
 ##TestCase.handleException(e)
@@ -193,11 +203,15 @@ try {
 ```
 
 <a name="TestCase.saveResult"></a>
-##TestCase.saveResult()
+##TestCase.saveResult(optForward)
 Saves the results of the current test case for further processing.
 
 Should be called in finally-block of the test case:
 
+**Params**
+
+- optForward `boolean` - indicate whether the result of the test case shall be immediately processed by the enabled forwarders. This means before the test suite has been executed to the end. If not specified in another way, this option is disabled! Default: `false`  
+
 **Example**  
 ```
 try {

diff --git a/src/common/src/main/resources/org/sakuli/common/libs/js/sakuli.js b/src/common/src/main/resources/org/sakuli/common/libs/js/sakuli.js
@@ -122,9 +122,9 @@ function TestCase(optCaseId, optWarningTime, optCriticalTime, optImagePathArray)
      *                 the execution time will never exceed, so the state will be always OK!
      * @param {number} optCriticalTime (optional) threshold in seconds, default = 0. If the threshold is set to 0,
      *                 the execution time will never exceed, so the state will be always OK!
-     * @param {boolean} optForward (optional) indicate whether the result of the test case shall be immediately
+     * @param {boolean} optForward (optional) indicate whether the result of the test step shall be immediately
      *                  processed by the enabled forwarders. This means before the test suite has been executed to
-     *                  the end. If not specified in another way, this option is disabled!
+     *                  the end. If not specified in another way, this option is disabled! Default: `false`
      * @memberOf TestCase
      * @method endOfStep
      */
@@ -195,16 +195,16 @@ function TestCase(optCaseId, optWarningTime, optCriticalTime, optImagePathArray)
      *      sakuli.saveResult();
      *  }
      *  ```
-     *
+     * @param {boolean} optForward  indicate whether the result of the test case shall be immediately processed by the enabled forwarders. This means before the test suite has been executed to the end. If not specified in another way, this option is disabled! Default: `false`
      * @memberOf TestCase
      * @method saveResult
      */
-    that.saveResult = function (forward) {
-        if (undefined == forward) {
-            forward = false;
+    that.saveResult = function (optForward) {
+        if (undefined == optForward) {
+            optForward = false;
         }
         Logger.logInfo("=========== SAVE Test Case '" + tcID + "' ==================");
-        Logger.logInfo("Forward of test case results enabled:  '" + forward + "'");
+        Logger.logInfo("Forward of test case results enabled:  '" + optForward + "'");
         //create the values
         var stopTime, lastURL = "", browser = "";
         stopTime = (new Date()).getTime();
@@ -213,7 +213,7 @@ function TestCase(optCaseId, optWarningTime, optCriticalTime, optImagePathArray)
         // Agent description can contain semicolon, replace globally
         browser = browser.replace(/;/g, ',');
         //call the backend
-        that.javaObject.saveResult(tcID, that.startTime, stopTime, lastURL, browser, forward);
+        that.javaObject.saveResult(tcID, that.startTime, stopTime, lastURL, browser, optForward);
     };
 
     /**