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 with built-in automation capabilities that can readily be 
       utilised for end-to-end testing and robotic processing. Automation is achieved through 
       Gherkin bindings called meta specs, composed with the Gwen DSL and maintained alongside 
       your feature files. An embedded Selenium engine executes scenarios according to the meta 
       you provide to perform operations in browsers for you.
       """

JavaScript Blocks​

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.

() => {
  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;
}

See also: arrow syntax as a preferred alternative to anonymous function wrappers

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 "() => { 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
        """
        () => {
          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