Gwen 3 Migration Guide

tip

See what's new in Gwen 3.

This guide will help you to migrate an existing Gwen project over to Gwen 3. If you want to start a new project from scratch, go straight to the getting started guide instead.

1. Setup

Choose your current Gwen setup

Standalone
Workspace

If you are using Gwen as a standalone application on your machine, nothing has changed in terms of setup and installation You can continue updating Gwen in the same manner you have been with prior versions. The setup instructions on our getting started page contain all the details you need know in that regard. You will however need to make some settings changes as described next.

Gwen workspaces were introduced in Gwen 2 and have been deprecated in favor of JS projects in Gwen 3.

Choose one of two options:

Migrate to a Gwen 3 JS project
Stay on a Gwen 2 workspace

Follow the instructions on our getting started page to create a new JS project with a fresh Gwen 3 setup, and then copy the following files from your workspace to your JS project:

Copy your workspace/gwen.properties file to js-project/gwen.properties
Copy all .feature files from workspace/features/ to js-project/gwen/features/
Copy all .meta files from workspace/meta/ to js-project/gwen/meta/
Copy all .properties files from workspace/browsers/ to js-project/gwen/browsers/
Copy all .properties files from workspace/env/ to js-project/gwen/env/

If you want to continue using your workspace, you will need to fix your Gwen version to a specific 2.#.# version. Workspaces are no longer maintained or released in Gwen 3, and automatic updates for them will no longer work. Open the gwen.properties file in your workspace directory in a text editor and amend the gwen.gwen-web.version property from latest to a specific Gwen 2 version that you want to use.

Amend setting

File: workspace/gwen.properties

# Gwen package version
# --------------------
# Gwen web version
gwen.gwen-web.version = 2.53.6

2. Settings

The following settings changes have been made to Gwen 3. Scan all your .properties files and update accordingly.

New names

The following settings have been renamed.

Prior name	New name
`gwen.feature.failfast`	`gwen.feature.failfast.enabled`
`gwen.rp.heartbeat`	`gwen.rp.heartbeat.enabled`
`gwen.web.capture.screenshots`	`gwen.web.capture.screenshots.enabled`
`gwen.web.browser`	`gwen.target.browser`

Removed alias

The following settings alias has been removed.

Removed alias	Always use this name
`gwen.behaviour.rules`	`gwen.behavior.rules`

New defaults

The following settings have new defaults. If you want to continue using prior defaults for these, explicity set them in your current .properties file.

Setting	Prior default	New default
`gwen.associative.meta`	`false`	`true`
`gwen.behavior.rules`	`lenient`	`strict`
`gwen.feature.mode`	`imperative`	`declarative`
`gwen.report.suppress.meta`	`false`	`true`
`gwen.auto.discover.data.csv`	`true`	`false`

New formats

Two new settings formats have been added:

HOCON (Human-Optimized Config Object Notation)
- The is now the recommended and default settings format
- A superset of JSON
- Maintained in *.conf files
JSON
- Pure JSON format
- Maintained in *.json files

The legacy Java style properties format is still supported and you can contine using properties files if you wish.

Properties
- Flat name = value pairs
- Maintained in *.properties files

Migrate your settings (optional)

Choose one of three options:

Convert to .conf
Convert to .json
Keep using .properties

Repeat the following to convert every .properties file you have:

Create a new file in the same location and with the same name but with a .conf extension
Convert each setting to its HOCON equivalent and save it to your new .conf file
- See example below
Discard your .properties file when done (or rename with the .properties.bak extension)

Example

Properties file: gwen.properties

# RP client settings
rp.endpoint = http://localhost:8080
rp.uuid = 28b262e7-8a9d-4928-b2a3-649562d5c63d
rp.project = default_personal
rp.launch = Gwen

# Gwen core settings
gwen.behavior.rules = strict
gwen.report.overwrite = false

# Gwen RP settings
gwen.rp.heartbeat.timeoutSecs = 5
gwen.rp.send.failed.errorBlocks = leaf
gwen.rp.send.failed.stepDefs = none
gwen.rp.send.stepDefs = inlined
gwen.rp.testCaseId.keys = auto

# Chrome settings
gwen.web.chrome.args.0 = --ignore-certificate-errors
gwen.web.chrome.args.1 = --window-size=1920,1080

# Gwen web settings
gwen.web.sendKeys.clearFirst = false
gwen.web.sendKeys.clickFirst = false
gwen.web.wait.seconds = 9

Equivalent HOCON file: gwen.conf

// RP client settings
rp {
  endpoint = "http://<host>:<port>"
  uuid = "28b262e7-8a9d-4928-b2a3-649562d5c63d"
  project = "default_personal"
  launch = "Gwen"
}

// Gwen settings
gwen {

  // General settings
  behavior {
    rules = "strict"
  }
  report {
    overwrite = false
  }

  // Gwen RP settings
  rp {
    heartbeat {
      timeoutSecs = 5
    }
    send {
      failed {
        errorBlocks = "leaf"
        stepDefs = "none"
      }
      stepDefs = "inlined"
    }
    testCaseId {
      keys = "auto"
    }
  }

  // Gwen web settings
  web {

    // General web settings
    sendKeys {
      clearFirst = false
      clickFirst = false
    }
    wait {
      seconds = 9
    }

    // Chrome settings
    chrome {
      args = [
        "--ignore-certificate-errors",
        "--window-size=1920,1080"
      ]
    }
    
  }
}

Repeat the following to convert every .properties file you have:

Create a new file in the same location and with the same name but with a .json extension
Convert each setting to its JSON equivalent and save it to your new .json file
- See example below
Discard your .properties file when done (or rename with the .properties.bak extension)

Example

Properties file: gwen.properties

# RP client settings
rp.endpoint = http://localhost:8080
rp.uuid = 28b262e7-8a9d-4928-b2a3-649562d5c63d
rp.project = default_personal
rp.launch = Gwen

# Gwen core settings
gwen.behavior.rules = strict
gwen.report.overwrite = false

# Gwen RP settings
gwen.rp.heartbeat.timeoutSecs = 5
gwen.rp.send.failed.errorBlocks = leaf
gwen.rp.send.failed.stepDefs = none
gwen.rp.send.stepDefs = inlined
gwen.rp.testCaseId.keys = auto

# Chrome settings
gwen.web.chrome.args.0 = --ignore-certificate-errors
gwen.web.chrome.args.1 = --window-size=1920,1080

# Gwen web settings
gwen.web.sendKeys.clearFirst = false
gwen.web.sendKeys.clickFirst = false
gwen.web.wait.seconds = 9

Equivalent JSON file: gwen.json

{
  "rp": {
    "endpoint": "http://<host>:<port>",
    "uuid": "28b262e7-8a9d-4928-b2a3-649562d5c63d",
    "project": "default_personal",
    "launch": "Gwen"
  },
  "gwen": {
    "behavior": {
      "rules": "strict"
    },
    "report": {
      "overwrite": false
    },
    "rp": {
      "heartbeat": {
        "timeoutSecs": 5
      },
      "send": {
        "failed": {
          "errorBlocks": "leaf",
          "stepDefs": "none"
        },
        "stepDefs": "inlined"
      },
      "testCaseId": {
        "keys": "auto"
      }
    },
    "web": {
      "sendKeys": {
        "clearFirst": false,
        "clickFirst": false
      },
      "wait": {
        "seconds": 9
      },
      "chrome": {
        "args": [
          "--ignore-certificate-errors",
          "--window-size=1920,1080"
        ]
      }
    }
  }
}

3. CLI

New `-c|--conf` option

The -p|--properties CLI option has been deprecated and replaced with the -c|--conf option which now accepts .conf, .json, and .properties files. The former will still work for .properties files until the next major release (and will be removed then). You should use the new launch option going forward.

Default `-r|--report` option

The output directory for all Gwen reports now has a default value configured in the new gwen.cli.options.report default CLI setting. So if you've been using Gwen as a standalone application, you no longer need to explicitly specify the -r|--report CLI option every time you launch Gwen and want reports to be generated. You can however continue to explicitly pass it through and override the default if you want to. Alternatively, change the default.

HTML reports by default

HTML reports will now be generated by default when you launch Gwen since the report output directory now has a configured default. They will also be generated by default for dry runs when you specify the -n|--dry-run switch.

If you don't want any reports generated, invoke Gwen with the -f|--format CLI option passing in none.

tip

1. Setup​

Choose your current Gwen setup​

Choose one of two options:​

Amend setting

2. Settings​

New names​

Removed alias​

New defaults​

New formats​

Migrate your settings (optional)​

Choose one of three options:​

Example​

Example​

3. CLI​

New -c|--conf option​

Default -r|--report option​

HTML reports by default​

1. Setup

Choose your current Gwen setup

Choose one of two options:

2. Settings

New names

Removed alias

New defaults

New formats

Migrate your settings (optional)

Choose one of three options:

Example

Example

3. CLI

New `-c|--conf` option

Default `-r|--report` option

HTML reports by default