REPL Console

Interactive Gwen shell

Since v1.0.0

Gwen comes with a REPL (Read-Eval-Print-Loop) console. This is a command line shell that prompts you for steps, evaluates them, and outputs their status in real time. It enables you to interactively observe the execution of your steps (and StepDefs) as you enter or paste them into the prompt which is very useful for automation development, debugging and analysis. Everything you enter is stored in a local history file and you can use the up and down arrow keys to recall previous inputs.

   __ ___      _____ _ __     _    
  / _` \ \ /\ / / _ \ '_ \   { \," 
 | (_| |\ V  V /  __/ | | | {_`/   
  \__, | \_/\_/ \___|_| |_|   `    
  |___/                            
                                   
Welcome to gwen-web v<version>
gweninterpreter.org

INFO - Default Gherkin feature dialect is: en
INFO - Environment context initialised
INFO - gwen-web.sh 

REPL Console

Enter steps to evaluate or type exit to quit..

gwen>

Starting the REPL

To start a REPL session, invoke the Gwen CLI without specifying the -b (or --batch) switch.

Project

Yarn

Open REPL

To open a new REPL session:

yarn gwen

To load meta and open the REPL:

yarn gwen -m path/to/file.meta

To execute a feature and open the REPL:

yarn gwen path/to/file.feature

npm

Open REPL

To open a new REPL session:

npm run gwen

To load meta and open the REPL:

npm run gwen -- -m path/to/file.meta

To execute a feature and open the REPL:

npm run gwen path/to/file.feature

pnpm

Open REPL

To open a new REPL session:

pnpm gwen

To load meta and open the REPL:

pnpm gwen -m path/to/file.meta

To execute a feature and open the REPL:

pnpm gwen path/to/file.feature

Standalone

Linux

Open REPL

To open a new REPL session:

gwen

To load meta and open the REPL:

gwen -m path/to/file.meta

To execute a feature and open the REPL:

gwen path/to/file.feature

Windows

Open REPL

To open a new REPL session:

gwen

To load meta and open the REPL:

gwen -m path\to\file.meta

To execute a feature and open the REPL:

gwen path\to\file.feature

REPL commands

Once in the REPL, you can type help at the gwen> prompt to list the available commands.

Gwen REPL commands:

help
  Displays this help text

env [switch] ["filter"]
  Lists attributes in the current environment
    Only lists visible attributes if no options are specified
    switch : (optional)
      -a : to list all attributes in all scopes
      -f : to list all attributes in the feature (global) scope
    filter : (optional) literal string or regex filter expression

:paste|paste
   Enters paste mode (for evaluating multiline steps)

history
  Lists all previously entered commands

!#
  Executes a previously entered command (history bang operator)
    # : the history command number

load <meta-file>
  Loads a meta file to pick up any changes
    meta-file : the path to the meta file relative to project root

Given|When|Then|And|But step-expression
  Evaluates a step
    step-expression : the step expression

(args) => body
  Evaluates a JavaScript arrow function 

q|exit|quit|bye
  Closes the REPL session and exits

ctrl-D
   If in paste mode: exits paste mode and interprets provided steps
   Otherwise: Closes REPL session and exits

tab
  Press the tab key for tab completion

right-arrow
  Press right arrow to accept auto suggestion

c|continue|resume
  Continue executing from current breakpoint step (debug mode only)

Tab completion

You can press the tab key at any time to lookup and select available commands, DSL Steps and custom StepDefs.

Tab completion is enabled by default. You can disable it by setting gwen.console.repl.tabCompletion to false.

Auto suggestions

Since v3.40.0

Auto suggestions based on your REPL history will appear in front of the cursor as your type. Pressing the right arrow key will accept them.

Auto suggestions are enabled by default. You can disable them by setting gwen.console.repl.autoSuggestions to false.

Paste mode

Should you attempt to enter a multiline step into the REPL, you will quickly discover that the first line will execute and fail as soon as you enter it without waiting for you to enter the remaining lines first. To address this, we have introduced a paste mode.

To enable paste mode, type :paste into the REPL prompt. The following will appear..

gwen> :paste

REPL Console (paste mode)

Enter or paste steps and press ctrl-D to evaluate..

You will then be able to enter or paste a multiple step without anything being executed when you press the enter key for each new line. For example, you could enter the following without any lines being executed prematurely:

 When the following items are added
      | Item          |
      | Get the milk  |
      | Walk the dog  |

Then when you're ready to execute or want to exit the paste mode, insert a new empty line at the end and press press ctrl-D. The REPL will then evaluate the step you entered before the empty line and return to the standard prompt when done.

Exiting paste mode, interpreting now..

gwen>  When the following items are added
            | Item          |
            | Get the milk  |
            | Walk the dog  |

INFO - Evaluating Step: When the following items are added
..
REPL Console

Enter steps to evaluate or type exit to quit..

gwen>

Meta reloads

Since v3.36.0

If you make changes to a meta file whilst in a REPL session, you can reload the changes by using the load command. This can save you time during meta development so you don't have to end your current REPL session and start a new one to pick up the changes.

Reload a changed meta file in your current REPL session as follows. New or changed StepDef's in the meta file will be immediately available after running the command.

gwen> load path/to/changed.meta

The path to the meta file must be relative to your project root directory where you launched Gwen.

Potential effects on state

Any scenarios in your meta that are NOT StepDefs will be re-evaluated on reload and this could result in side effects that modify the current state. Consider refactoring your meta to only declare StepDefs to avoid this impact.

Debugging

Breakpoints

Since v3.2.0

Breakpoints can be added to any feature or meta steps by prefixing their expressions with @Breakpoint . These are ignored unless debugging is explicitly enabled with the -d|--debug CLI option.

Example

Breakpoint in feature file

File: features/todo.feature

Feature: Add todo items
 
  Scenario: Create todo list
    Given a new todo list
     When the following items are added
          | Item          |
          | Get the milk  |
          | Walk the dog  |
     Then @Breakpoint the list will contain 2 items

info

To activate breakpoints, launch Gwen in debug mode by specifying the -d|--debug CLI option.

When a breakpoint on a step is encountered and debugging is enabled, Gwen will pause execution, open the REPL, and prompt the user to continue execution from that step or to quit (or to perform other REPL operations).

Sample breakpoint prompt in REPL

Feature: Add todo items

  Scenario: Create todo list
    Given a new todo list  [6s 344ms] Passed
     When the following items are added
          | Item         |
          | Get the milk |
          | Walk the dog |  [2s 200ms] Passed

Paused at features/todo.feature:9
    Then @Breakpoint the list will contain 2 items
Enter c to continue or q to quit (or type help for more options)..

gwen@Breakpoint> _

JavaScript Functions

Since v3.56.0

Develop and experiment with JavaScript arrow functions by entering them directly in the REPL.

gwen> Given name is "Gwen"

  [10ms] ✔

gwen> name => name.toUpperCase()

  'GWEN'

gwen> 

Exiting the REPL

To exit the REPL, enter q, quit, exit, or bye or press ctrl-D at the gwen prompt.