Step-by-Step: Migrating a Legacy Selenium Java Suite to Modular Playwright TypeScript

Migrating a legacy Selenium Java suite to a modular Playwright TypeScript framework involves several key steps to transition from the verbose and flaky Selenium approach to the more robust and efficient Playwright framework.

Firstly, the project structure needs to accommodate both the existing Selenium tests and the new Playwright tests simultaneously. This can be achieved by initializing a new Playwright project within the root repository directory using the command `npm init playwright@latest`. This allows for an incremental migration of tests from the legacy system into the new modular Playwright structure.

Secondly, the Page Object Model (POM) concept prevalent in Selenium needs to be translated into modular TypeScript code using Playwright’s syntax. Instead of Java classes, developers will create TypeScript classes that export Page objects. For instance, the Java `LoginPage` class with its locators for the email input and submit button can be converted into a TypeScript `LoginPage` class.

This class will contain `Locator` objects for these elements, which are created by calling methods such as `getByLabel` or `getByRole` on a Playwright `Page` object. The `LoginPage` class will also include an asynchronous `login` method that fills the email input with a given email and clicks the submit button, utilizing Playwright’s auto-waiting capabilities.

Thirdly, the framework’s built-in waiting mechanisms are utilized to eliminate the need for explicit waits seen in Selenium. Playwright automatically waits for elements to be in a stable state before executing actions, reducing test flakiness. This is achieved by using Playwright’s contextual wait mechanisms, which automatically check for the visibility, actionability, and stability of elements before performing interactions.

Lastly, special attention is given to handling more complex scenarios such as cross-domain iFrames and cookie persistence. Selenium often requires manual intervention to switch contexts or manage session storage. Playwright simplifies these tasks with features like `frameLocator`, which allows for direct interaction with elements inside iframes without the need for explicit switching.

Additionally, Playwright can persist the browser’s storage state, such as cookies and local storage, making it easier to replicate login states across different test files without the cumbersome process of re-entering login credentials in Selenium.