Twist to Gauge migration

This lists all the steps that are required to migrate a Twist project to a Gauge project. This will involve a Twist upgrade(if you are not already on the latest). The instructions for the entire process are listed here. 

 We have a 3 part video series which shows you how to migrate a Twist suite to a Gauge suite. You can find them here. If you prefer written instructions, then this document gives you everything you need for migration. 

Upgrade Twist

Steps to be followed to upgrade Twist and get the migration utility:

• Go to "Preferences -> Install/Update -> Available Software Sites". You can also use "Help menu -> Install New Software -> Available Software window -> Available Software Sites link".

• Click on "Add" button to bring the "Add Site" window, enter URL 'http://download01.thoughtworks.com/twist/update-site' and name 'Twist Update site' and press "OK" button. You will see that this new site is added to your list of update sites. Ensure 'Twist Update site' is checked amongst 'Available Software Sites'. Close the preferences window.

• Click on the help menu and select 'Check for Updates'.This will open the Updates window with a list of pending updates from the site we just added.  

• Please make sure "Group Items by Category" option is unchecked. Then select all the Twist plugins to update(this will include the Twist to Gauge Migration plugin). The install button should now be enabled, click it and follow the instructions to update. Refer to the screenshot below.

• After the upgrade process, Restart Twist when prompted.

• Right click on the project -> Select "migrate to current version". This will migrate your Twist project to be compatible with the latest version of Twist. 

Pre-Migration

Steps to be followed before migration:

• Compile, build and refresh your Twist project. This ensures all files needed for the Twist to Gauge migration are available.

• Install Gauge from getgauge.io Make sure Gauge is in PATH.

• Install Gauge Java plugin. You can do this with the command gauge --install java from the command prompt/terminal. 

• Install Gauge plugin on IntelliJ. You can do this from IntelliJ Preferences. Select Gauge under Plugins and install. This is how you would install the plugin.

Migrate to Gauge

Steps to be followed to migrate the Twist project to a Gauge project:

• Choose the Twist project to be migrated and right click on it. Select and choose the location for your corresponding Gauge project.

• This starts migrating the Twist project. You can check progress on the console output.

• Once the migration operation is completed, a summary of migration is created. You will see this inside the Twist project, within the project directory.

Post Migration

How to work with the migrated project?

• Open a new project in IntelliJ -> File -> New Project-> Gauge -> Change project location: path to migrated project]. Refer to the screenshot below. We recommend this over opening the Gauge project directly because this will set all dependencies correctly. It also ensures that Gauge-java is installed correctly. 

• When the Twist project is migrated to Gauge, the resources that are not directly related to steps and implementation(example SQL directory, reports etc.) cannot be copied over. You will need to explicitly include these inside the project. You will have to copy these from your Twist project.

• The migration may copy some class or jar directories into the libs directory into your new migrated gauge project. These directories need to be added as dependencies into the IntelliJ project. To do this, open the project properties -> Libraries. Select add (+) -> Java and select the nested directories under the libs folder. For example, a gauge webdriver project will have a libs/com.thoughtworks.twist.webdriver.recorder directory that needs to be added as a java dependency.
• Compile the project in Intellij (Run Ctrl/Cmd + F9). If there are compilation issues because of some dependencies not available in the project, you can copy the required jars from TWIST_INSTALLATION_DIR/plugins into the MIGRATED_GAUGE_PROJECT/libs directory. 

• The migration summary report will give you details about all scenarios/steps that did not get migrated, and the reasons for it. Some of these need manual fixing. This document details the kind of errors you will see, why and how you can fix them.

In case you encounter any errors during migration or while trying to execute the Gauge project after successful migration, we have compiled a list of common problems, reasons, and the resolution .You have find this here.