Future of Angular E2E & Plans for Protractor

TLDR

The Angular team plans to end development of Protractor at the end of 2022 (in conjunction with Angular v15).

Why?

Protractor was created in 2013 when WebDriver APIs were not yet a standard and end-to-end (e2e) tests were hard to write due to lack of support for async / await. To solve this problem, Protractor wraps selenium-webdriver and abstracted asynchronous operations from developers with the use of Control Flow.

Since then, the JavaScript standard and ecosystem advanced considerably, providing modern syntax and much better development tools. Nonetheless, Protractor is not able to leverage such technology without forcing users to rewrite their tests. Meanwhile, robust alternatives have emerged in the web testing space. Developers will see more benefits from adopting a more modern testing tool than from updating to a breaking version of Protractor which does not provide additional functionality or developer ergonomic improvements.

We would like to hear from the community on

• the deprecation timeline
• what we can do to provide reliable integration with third-party solutions
• how users can transition by following migration guidelines
• additional concerns that would ensure a smooth transition

This RFC will close on Friday April 16, 2021.

---

State of Protractor

The Angular team created Protractor in 2013 when WebDriver APIs were not yet a standard and end-to-end (e2e) tests were challenging to set up. The proliferation of callback patterns in JavaScript back then made asynchronous operations difficult to write and manage.

Protractor, echoing the approach taken by the underlying selenium-webdriver, solved this problem by managing promises via Control Flow. Control Flow makes asynchronous calls appear synchronous, thereby avoids the use of Promises entirely.

This strategy worked well for some time, but as the JavaScript standards and toolings evolve, Protractor regressed. Starting from ES2017, async / await makes handling Promises significantly easier because they no longer have to be chained. However, async / await is fundamentally incompatible with Control Flow, and support for Control Flow is dropped from selenium-webdriver v4.0 completely. Protractor, being dependent on selenium-webdriver, is not able to upgrade to the new version without introducing a huge breaking change and forcing users to do a migration for all their tests.

Besides dropping support for Control Flow, making Protractor compatible with ES2017 involves a significant amount of work to overhaul its implementation. Legacy dependencies such as jasminewd2 and Q promise library ought to be removed, which will bring about further breaking changes.

Since Protractor was initially designed to support AngularJS, many of its features like locators and mock modules are specific to AngularJS. These features only work in AngularJS and not Angular. They will no longer be relevant once development on AngularJS ceases by December 31, 2021.

Removing Control Flow and dropping AngularJS-specific features would make Protractor essentially just a wrapper around selenium-webdriver that provides no additional functionality.

Current Landscape for Web Testing

Many testing solutions have appeared since the creation of Protractor, and they offer better stability and much improved support for features like cross-browsers testing. Some even eschew the WebDriver standards completely in favor of using the DevTools protocols directly.

In order to understand the adoption trend of these alternatives in the Angular community, we conducted a survey on e2e testing in January 2021. We received close to 1000 responses and got a lot of feedback from the community. A clear signal that we received is that there is no one-size-fits-all solution for all Angular projects out there. Fewer than 20% of the respondents use Protractor in their project. Some users prioritize the cross-browsers support that the WebDriver standards guarantee, whereas other users prefer the stability and flexibility that DevTools protocol offers. A similar survey focused entirely on enterprise customers yielded comparable results.

Moving Forward

Deprecating Protractor is not a decision that is taken lightly by the team. Inside Google, we support thousands of projects and hundreds of thousands of test targets that depend on Protractor. After evaluating the costs and benefits of updating Protractor vs migration effort imposed on users, we conclude that the best strategy to set users up for success in the long term is to encourage migration to a more modern and framework-agnostic testing platform. The reasoning is as follows:

Removing Control Flow from user code is a gigantic effort because it forces users to update all their tests. Google went through this effort, and it took a major infrastructure team half of their time in 2018. Even then, they could only migrate tests written in TypeScript due to the availability of more robust tooling for source code analysis and transformation.

After going through such a massive endeavour, we realize the “new” Protractor is no better than other existing solutions. The only feature that differentiates Protractor from selenium-webdriver at this point is the ability to automatically wait for the application under test to become stable (waitForAngular feature in Protractor).

Although waitForAngular is useful, it strongly couples the testing platform to the Angular framework. Some teams at Google have found that solutions that do not require knowledge of Angular can perform the tests equally well by using a robust retry strategy. We believe this is how e2e testing should be done going forward, and projects in Google are already converging towards a testing platform that is WebDriver compliant and framework agnostic. This allows our web test team to maintain a single solution for all web applications.

Externally, there are many excellent alternatives available to the open source community, such as:

1. Cypress
2. PlayWright
3. Puppeteer
4. Selenium-webdriver
5. TestCafe
6. WebdriverIO

(The list is sorted in alphabetical order and is non-exhaustive.)

Deprecation

The most important focus for the Angular team is to ensure a smooth transition for Protractor users. We have been engaging with different vendors to ensure

• there is sufficient documentation / tooling to help users migrate to other platforms
• third-party platforms integrate well with Angular CLI, so that CLI configurations are automatically handled by vendor-specific builders

So far, the Angular team has reached out to the teams at Cypress and WebdriverIO to achieve the goals above. We will provide regular updates as more resources become available. If there is a particular platform that you’d like us to reach out to, please let us know in the comments below.

Our proposed deprecation timeline is as follows:

• Angular version 12 (May 2021)
  • Announcement of deprecation
  • Angular CLI will not include Protractor for new projects
  • Show warning when @angular-devkit/build-angular:protractor is used
  • Only PRs that address security issues and fixes for browser releases that break Protractor tests will be merged
• Angular version 15 (end of 2022)
  • End of development on Protractor

No decision is final until we assess all the feedback from this RFC.

Extended LTS

For users who require extended long-term support after the end of life of Protractor, we suggest reaching out to our external partners:

• flare.build
• herodevs

If your team / company provides similar services, please let us know!

FAQs

1. What about Component Harnesses? Angular CDK’s component harnesses include a ProtractorHarnessEnvironment for using harnesses in Protractor. This environment will be deprecated and replaced with a new environment backed by selenium-webdriver. The harness APIs themselves will be unchanged.
2. How will Angular CLI handle ng e2e for new projects starting from version 12? The CLI will not include a default e2e builder for new projects, and users will decide which third-party builder to install. This is because picking an e2e platform really depends on the requirements of the project and there is no clear best fit for all Angular projects.
3. In version 15, would all Protractor tests break? The Protractor builder will continue to work until version 15. After that, we plan to remove the Protractor builder (@angular-devkit/build-angular:protractor), which means ng e2e will no longer run Protractor. However, we are open to revising the timeline based on user feedback. Please let us know in the comments below.
4. Protractor is useful because it automatically waits for the application to become stable. How can I use that in other platforms? Under the hood, Protractor uses Testability provided by @angular/core to check if the app is stable. This feature can be integrated into other platforms in a straightforward way. See the example for selenium-webdriver.
5. Which e2e framework is the lowest effort and cost to migrate to from Protractor? In terms of APIs, selenium-webdriver is most similar to Protractor because it is used under the hood. If your tests still use Control Flow, you’ll have to remove it first by adding async / await to the Protractor calls. After that, you can replace the Protractor methods with those in selenium-webdriver. Although they are not 1:1 replacements, they are very close.
6. Where will e2e migration strategies be documented? We are consolidating a list of migration strategies doc written by vendors and community members. See Links section below.
7. What other packages will be deprecated along with Protractor at the end of 2022?
   • protractor-cookbook
   • jasminewd
   • webdriver-js-extender
   • blocking-proxy
   • webdriver-manager
8. My team just did a migration to disable Control Flow. What are our options? It is possible to create a thin wrapper around selenium-webdriver to provide APIs that are compatible with Protractor’s. This is an idea that needs further exploration. Please let us know in the comments below if such tool is useful to you.

Open questions

1. Should the Angular team provide a different deprecation timeline?
2. In addition to migration docs and CLI integration, how can the Angular team support Protractor users in the transition to other platforms?
3. What are the alternatives to deprecating Protractor?

Links

This section is a work in progress. We will continue to consolidate more links and migration guides here.

1. Migrating from Protractor to Cypress https://nx.dev/latest/angular/modern-angular/protractor-to-cypress
2. Cypress official doc for Protractor users (placeholder link for now, will be live in the future) http://on.cypress.io/protractor-to-cypress

[mgechev]

@pavankjadda we’re working with the Cypress team to ensure smooth integration with the Angular CLI.

[christian-bromann]

Hey folks 👋 , this is Chris maintaining the WebdriverIO project. First of, big thank you to everyone involved developing Protractor, it has been a great framework and WebdriverIO has adopted a couple of feature ideas from it. We are glad that the Angular team has reached out to us to include WebdriverIO as an transition option. The team is happy to offer a free, open governed and flexible framework, hosted under the OpenJS Foundation alongside projects like Node.js and webpack.

WebdriverIO allows you to leverage both the ability to run true cross browser testing based on WebDriver as well as a lot of debugging and introspection capabilities through the DevTools protocol. With the help of various plugins the framework provides running performance and PWA audits through Google Lighthouse as well as mocking and stubing any kind of browser requests. It comes with a Jest style built in assertion library and tons of reporters, some maintained by the project some by the community.

We are currently actively working on the following items to make the transition for Protractor users as smooth as possible:

• build an Angular CLI schematic (see webdriverio/webdriverio-schematics ✅ )
• setup a codemod to help transform Protractor code into WebdriverIO commands, see @wdio/codemod ✅
• ~[ ] Add Angular framework stabilizer~ Won’t do: @cnishina mentioned that there aren’t any Angular specific wait mechanism needed anymore
• Write up docs with a step by step description how to transition over (webdriverio/webdriverio/issues/6678 ✅ )

Feel free to raise an issue in the WebdriverIO project if you see anything else from the Protractor ecosystem you want to see adopted. WebdriverIO, as it is right now, can already being used for any kind of Angular projects but with these additional initiatives we hope to help with the transition even further. Cheers!

Update (16/04/2021): we implemented and battle tested a codemod that transforms ~90% of Protractors API and we continue to extend it as we support the migration process of various organisations. A migration guide was drafted and will be published soon.

Update (19/04/2021): we released a migration guide that explains how a Protractor migration can be run using our codemod. The guide will be extended as we get more feedback from folks running into issues.

Update (20/04/2021): a community member has build an expected condition library that is a drop-in replacement for the Protractor one. We will update the codemod within the next days to simplify the migration. Thanks @elaichenkov!