Skip to main content

Doc Strings

Since v2.9.0

Every step in the Gwen DSL that includes a string literal parameter surrounded by quotes at the end of the step expression can accept a Doc String value.

Doc Strings as parameters to StepDefs​

As of gwen-web v2.53.0 (gwen core v2.34.0), Doc strings can also be passed as parameters to DSL steps and StepDefs too. If the Doc String contains a multi-line value then it can only be passed to parameters that are declared in the Doc-string-able position (that is: string parameters surrounded by quotes declared at the end of the step expression).

This is handy when you want to specify a multiline string literal as the last parameter to a step.

Some examples follow..

Multiline Text​

One use case is multiline strings. In the absence of Doc Strings there was no way to pass in multiline strings or paragraphs of text. You can now do this as follows:

  Given my paragraph is
       """
       Gwen is a Gherkin interpreter that turns Given-When-Then steps into automation instructions and executes
       them for you so you don't have to do all the programming work. It has an abstracted evaluation engine
       allowing any type of automation capability to be built and mixed in. Meta specifications (also expressed
       in Gherkin) are used to capture automation bindings and allow you to compose step definitions by mapping
       'declarative' steps in features to 'imperative' steps in engines that perform operations.
       """

JavaScript Function Bindings​

Doc Strings can also be used to define Multi-line JavaScript functions.

For example, consider the following script that returns the current date in yyyy-mm-dd format.

(function() {
  var d = new Date();
  var year = d.getFullYear();
  var month = ('0' + (d.getMonth() + 1)).slice(-2);
  var day = ('0' + d.getDate()).slice(-2);
  return year + '-' + month + '-' + day;
})();

In the absence of Doc Strings, you would have to compact this to a one-liner expression and use it as follows (which is inelegant and hard to read):

Given the current date is defined by javascript "(function() {var d = new Date(); var year = d.getFullYear(); var month = ('0' + (d.getMonth() + 1)).slice(-2); var day = ('0' + d.getDate()).slice(-2); return year + '-' + month + '-' + day; })();"

With Doc Strings, you can now do this as follows instead:

  Given the current date is defined by javascript
        """
        (function() {
          var d = new Date();
          var year = d.getFullYear();
          var month = ('0' + (d.getMonth() + 1)).slice(-2);
          var day = ('0' + d.getDate()).slice(-2);
          return year + '-' + month + '-' + day;
        })();
        """

Sample Reports​

The javascript Doc String in this report includes the optional JavaScript content type annotation at the opening triple quotes""". Currently, Gwen just renders this literal in grey, but could in future use it for syntax highlighting.

Doc Strings in reports