Migrate a project to the latest version of Twist

As newer Twist versions are released, some of the settings of existing Twist projects may need to be migrated such that they work seamlessly with updated versions of Twist.

How to migrate a Twist Project?

Twist automatically detects and prompts the user to migrate a project if necessary, when the user opens a Scenario in the Twist IDE. A project, can also be manually migrated by using the option available on the context menu on a project in the Scenario View.

Prerequisites for migration:

During Migration, a dialog would pop up that lists outs the operations performed during migration. If the project cannot be migrated for some reason, then a dialog box would pop up with an explanation. Please fix the problem encountered and try re-running Migration again.

Migration can also be invoked in verbose mode such that it lists out more details of the activities performed. Please create a log4j.properties file with the logger entry shown below and add it to the classpath. (Refer to the Appendix below for more information)

log4j.logger.com.thoughtworks.twist.migration = DEBUG

The following describes the changes that would be performed as a part of automated migration in Twist.

Migrating to 1.1 GA

Apart from updating the Twist version number, migration to 1.1 GA (from 1.0 GA) has no other impact.
Changes in 1.1 GA
  • Support for specifying the location of html reports: Twist uses the property twist.local_report_location to write the html report. By default, this property defaults to the value reports. If the execution contains Manual Scenarios, the report name would contain the suffix "M". For example, "2009-01-25,09-15-23-M".

Migrating to 1.0 GA

Changes in General Availability version(1.0)

  • UTF-8 Encoding: Twist now uses "UTF-8" as the default encoding for new projects. If an existing project has an encoding specified, that encoding will not be changed during migration.
  • Support for generating local reports: Twist uses the property twist.generate_local_report to decide if it should create an HTML report each time a scenario is executed in the Twist IDE. If set to true, then the reports are generated in the "reports/yyyy-mm-dd,hh-mm-ss" folder.

Changes in Beta update version

  • Twist now uses a file twist-exclude-classes.properties where you can specify classes that should be excluded from auto-completion, code navigation etc.
  • Contexts do not implement org.springframework.context.LifeCycle anymore. They are plain Java classes that have setUp() and teardown() methods instead of start() and stop(). setUp and teardown methods can be overloaded, which means you can now have contexts that take arguments.
  • Properties used by Twist for configuring Selenium have changed.
    • Twist does not use selenium.port and selenium.proxyInjectionMode any more. Instead it uses a new property selenium.server.options like so: selenium.server.options -port
    • Proxy injection mode can be set as an argument to selenium.server.options as argument -proxyInjectionMode. If proxy injection mode is not required, one should exclude the option -proxyInjectinMode in seleium.server.options property
    • The property selenium.highlight has been renamed as twist.selenium.highlight
    • Twist uses twist.selenium.enableImplicitWait as the property that decides if implicit wait is needed or not. Details of the properties can be found in the default twist.properties file (located in $project/src) folder.
    • Twist also uses a different bean configuration to load Selenium beans. These changes occur in the applicationContext.xml file. The seleniumDriverFactory bean uses three new properties
      • serverOptions, browserLauncher and browserURL respectively. By default, they use the values of the properties selenium.server.options, selenium.browserLauncher and selenium.browserURL respectively. So, if these properties are specified, say in twist.properties file, then the specified values of these properties will be used by the Selenium bean.
      • The seleniumDriverFactory bean uses an additional constructor-arg. It uses the value of the property twist.selenium.enableImplicitWait as the argument.
      • In addition, it has a new property highlight which controls if Selenium should highlight matching html elements.
      • The bean with id = defaultTwistSelenium is not used anymore.
    • Also, the folder junit-transform found at the top level folder is not used anymore. It may be deleted.
    • The twist.version file is updated and has the version as 1.0.0.5898-GA

Other Changes

  • All internal Twist specific configuration files, such as .twist.settings are moved to twist-conf folder under the project's root folder.
  • A Twist project now has a "Twist nature" associated with it. It also uses a new incremental builder named Scenario Builder to build scenarios.

How Migration works

Twist looks at the existing project's structure to determine which version of Twist it belongs to. The project is migrated one step at a time such that it becomes compatible with the latest Twist version. As the last step of migration, Twist updates the project's Twist version to be the same as the version of the Twist application that is performing the migration.

If any of the steps performed as a part of migration encounters an error situation, migration aborts at that point. It does not, however, revert back any changes made to the project. Please fix the problem reported by Migration, and try re-running Migration again.

The Twist version number of the project can be seen in the property file "twist.version" under twist-conf folder in the project's root folder. This should not be edited. Editing the contents of this file may result in undefined failures.

Troubleshooting

Migration does not allow re-runs if the project is already migrated. If for any reason you wish to start all over again, you may have to make certain changes to your project such that Migration considers the project. For instance, you could delete the "twist-conf" folder, refresh the project and run Migration. Twist would assume that the project being considered is a Twist Beta compatible project, and it would migrate the project to GA.

Appendix

How to turn on verbose mode in Migration

Create a log4j.properties file. Append the following contents to the file. Place the file in the classpath of the project. (One could, for example, create a new source folder, say, "src-log" and place the properties file in this source folder). Now, Migration would print more details of the activities it performs during migrating a project.

log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r %-5p %c %x - %m%n

log4j.logger.Twist.migration=TRACE