TestCafe 2.0 Migration Guide

TestCafe 2.0 includes a breaking change. The framework’s built-in TypeScript compiler has been updated from version 3.9 to version 4.7.

If you only use JavaScript tests, the changes to the TypeScript compiler do not affect you. You can skip this migration guide and upgrade to TestCafe 2.0 straight away.

Overview

TypeScript 4 was introduced in August of 2020. Since then, many TestCafe users opted to use an external TypeScript 4 compiler. To accommodate these users, the TestCafe team decided to replace the bundled TypeScript 3 compiler with a TypeScript 4 compiler.

The vast majority of TestCafe users should not experience any issues during the upgrade. However, since TypeScript does not follow the semver versioning policy, even minor TypeScript updates contain breaking changes. Some TypeScript users may need to perform additional actions to ensure the compatibility of their test code.

Migration strategies

Most TypeScript users should not experience any issues when they upgrade to TestCafe 2.0.

1. To make sure that you don’t run into any breaking changes, install the latest version of the framework on your local machine.
2. Run your TestCafe tests locally.
3. TestCafe outputs TypeScript compilation errors to the console. If your tests yield compilation errors, review the errors and decide whether you want to refactor your tests or use an external TypeScript compiler.

Option 1: Refactor your tests

If your tests yield compilation errors, the best course of action is to refactor your tests. This will ensure the long-term security and stability of your test suite, and should not take a lot of time.

1. View the list of breaking changes that occurred between the release of TypeScript 3.9 and TypeScript 4.7. If you notice a change that affects you, edit your tests in compliance with the new standard. Refer to the TypeScript documentation for more information.
2. Run your tests locally and fix compilation errors as they occur.

Option 2: Use an external TypeScript compiler

If you lack the resources to refactor your tests right now, you can use an external TypeScript 3 compiler with TestCafe 2.0.

1. Install an older version of the TypeScript compiler:

   npm i typescript@3
   

2. Locate the compiler binary:

   npm list typescript@3
   

3. Use the compiler-options TestCafe option to customize TypeScript compiler settings. To specify a custom TypeScript compiler, pass the path of the custom compiler binary to the typescript.customCompilerModulePath property.

   • CLI:

     testcafe chrome test.ts --compiler-options typescript.customCompilerModulePath=../typescript@3
     

   • Configuration File:

     {"compilerOptions": 
         {"typescript":   
             {"customCompilerModulePath": "../typescript@3"}
         }
     };
     

   • Test Runner API:

     runner.compilerOptions({
     "typescript": {
         customCompilerModulePath: '../typescript@3'
     }});