Protractor version 4.0.0 is out and you can now write Protractor tests with TypeScript! Hooray! If you are unfamiliar with TypeScript there are probably a lot of questions like: What’s TypeScript? How should we setup the project? Can I mix and match JavaScript with TypeScript in Protractor?
So let’s get started…
What’s TypeScript?
Typescript is a typed superset of JavaScript that compiles to plain JavaScript.
Its best to get it from the source: I would suggest checking out the youtube video (above) and The Changelog podcast where Anders Hejlsberg goes over TypeScript latest and greatest features. Basic overview: static types provide statement completion, find references, navigation to definitions, and refactoring.
Why should we use Protractor with TypeScript?
Protractor with TypeScript should feel very similar to the JavaScript flavor of Protractor. Protractor with TypeScript provides properties tied to the global namespace through a simple import. From that imported property we can get autocompletion, method signature, and the JSDoc. For example, if you are trying to fork the browser but don’t know what that function was called, try it out.
Maybe it starts with “get”? I think it is “getFork”…
Okay that did not work…I could just reference the protractortest.org API documentation but I want another shot at this. Maybe it starts with “fork”.
Woohoo! Looks like I guessed correctly. The function is called forkNewDriverInstance and it has:
- parameters for optional parameters opt_useSameUrl and opt_copyMockModules
- also we know that both opt_useSameUrl and opt_copyMockModules are booleans
- returns something of type Browser
Just with that attempt to find the function forkNewDriverInstance, we see that our TypeScript-supported text editor provides some helpful hints including the function signature, parameter types, and the definition from the JSDocs.
Doesn’t this look oddly familiar? If you’ve visited the protractortest.org API page, this is the exact same text for forkNewDriverInstance. High fives if you guessed correctly!
The benefits of TypeScript as shown above are available via any text editor or IDE with TypeScript support. Visual Studio Code readily supports TypeScript. Text editors such as Atom and Sublime Text, however, require a plugin (atom-typescript and TypeScript-Sublime-Plugin). There are other editors / IDE listed on typescriptlang.org website.
Setting up Protractor with Typescript
Project setup is very typical for a TypeScript project. We have an example in the protractor repository which might be a good place to start. There are several files you will need:
- package.json
- tsconfig.json
- typings.json
- protractor configuration file
- spec files
package.json
The package.json from the example has several dependencies. We’ll go over the dependencies and why we need them / use them.
- typings — the typings dependency is there to install ambient typings.
- typescript — to transpile TypeScript via the tsc (TypeScript compiler)
- protractor — because we want to write tests! In addition to providing the protractor node module, it also has information where the type declarations are located. In the protractor package.json, the “typings” are located at “built/index.d.ts”
tsconfig.json
When a tsconfig.json file is present in the project, it provides instructions to which files to convert TypeScript to JavaScript via the tsc (TypeScript compiler). You can find more information at the typescriptlang.org site about tsconfig.json.
typings.json
The typings.json file lets typings know which ambient declaration files to download from DefinitelyTyped. In the example, we are using node and jasmine.
A quick note: there is a DefinitelyTyped Protractor file. This is from an older version of Protractor and should not be used with the current version.
Protractor Configuration file
Creating the configuration file in TypeScript has benefits. When creating a configuration file, you might forget if it is “spec” or “specs”, just start typing and it is easy to find out that it is called “specs” and “specs” is a string array.
Spec file
TypeScript spec files should look the same as spec files when you were doing JavaScript. The only difference is that we are importing Protractor globals. This is where having gifs of Protractor in action helps:
Hold on, it appears that we are importing browser, element, by, and ExpectedConditions, but none of the jasmine types. With the tsconfig.json file, we are specifying to include the *.d.ts files from the typings directory so we do not have to import “describe”, “beforeEach”, and “it”.
Protractor with TypeScript upgrade
The only thing that changes is that now you will have to transpile your TypeScript to JavaScript. The Protractor command line interface still requires a JavaScript configuration file with specs in JavaScript.
This means that you could have a mix-and-match of JavaScript created files and TypeScript created files. If you have several tests already written in JavaScript, you do not have to change them and you can start writing your next tests in TypeScript.
Slowly Moving Forward
Currently, Protractor adds types tied to the public API; however, not all type declarations for selenium-webdriver are present. Selenium-webdriver typings from DefinitelyTyped have not been updated in a while, some additional work will need to happen to have a complete story for Protractor with TypeScript.
We are also actively working on resolving some old style require issues that have popped up from the 4.0.0 release and will have a hot fix soon.
