Files
e2e/docs/migrate/selenium.mdx

156 lines
11 KiB
Plaintext

---
title: From Selenium
description: Rewrite Selenium flows in TypeScript with locators, retrying assertions, and agent goals.
"og:image": "https://e2e.com/docs/images/og/migrate/selenium.png?v=32737f50da"
"twitter:image": "https://e2e.com/docs/images/og/migrate/selenium.png?v=32737f50da"
---
import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
export const migrationPrompt = `Migrate this project's Selenium tests to e2e, one flow at a time. Docs: \`https://e2e.com/docs/migrate/selenium.md\`
1. Read the migration guide above. It maps Selenium config and WebDriver calls to e2e, and lists what e2e doesn't have yet.
2. e2e tests are TypeScript. If the Selenium suite is Java, Python, or another language, ask me where the new test project should live, for example an \`e2e/\` folder with its own \`package.json\`.
3. If that project has no e2e config (\`e2e.config.ts\`, \`.mts\`, \`.js\`, or \`.mjs\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent) there. It writes a config and an example test, and installs nothing yet.
4. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
5. If you ran init, ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
6. Set the target's \`app\` to the URL every \`driver.get\` used, and the command that starts the app if the suite starts it. Move passwords and tokens into \`credentials\` or \`secrets\`.
7. Install dependencies.
8. List the page objects and the flows that use them, and ask me which to move first. Suggest one page object and its flows.
9. Rewrite those flows as \`.e2e.ts\` files under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default) with the guide's tables. Check "What e2e doesn't have yet" before you port a flow. If it lists a call the flow needs, use the "Use today" workaround, or leave the flow in Selenium and say why. Prefer role, label, and test id queries over CSS and XPath. Replace every wait and \`Thread.sleep\` with a locator assertion. Narrow queries that match several nodes. Turn the page object's setup code into a fixture.
10. Keep navigation and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted interactions breaks often, propose an \`agent.act\` goal for it instead.
11. Run the new files with \`npx e2e run <file>\` and fix them until they pass. Keep the Selenium tests until I confirm they can go.
12. Summarize which flows moved, which stayed in Selenium, and why.`;
e2e replaces a Selenium suite with TypeScript tests. Locators find nodes by
role and label, and assertions retry until they pass or time out. A Java or
Python suite needs a rewrite, so run both suites and move one flow at a time.
<SetupPrompt>
<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
</SetupPrompt>
For a migration that spans several sessions, the [`migrate-to-e2e` skill](/coding-agents#migrate-an-existing-suite) records what moved in a progress file and keeps the old suite running until you retire each test.
## Port the config
<Note>Install e2e with the [quickstart](/quickstart). Only agent calls need a model, so the example below runs without one.</Note>
| Selenium | e2e |
| --- | --- |
| The URL in every `driver.get` | `app: { url }` on the target, then relative paths |
| Starting the app in a script | `app: { url, command }`, see [Starting your app](/web#starting-your-app) |
| One driver per browser | One target per `web({ browser })` build, `chromium`, `firefox`, or `webkit`, not Chrome, Edge, or Safari |
| Selenium Grid | `workers` for parallel runs, a [browser provider](/browser#hosted-browsers) for hosted Chromium |
| Passwords from `System.getenv` | `credentials` or `secrets` in the config, see [Authentication](/authentication) |
## Rewrite one flow
```java title="Selenium"
driver.get("http://localhost:3000/login");
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(visibilityOfElementLocated(By.id("username"))).sendKeys("admin@example.test");
driver.findElement(By.id("password")).sendKeys(System.getenv("ADMIN_PASSWORD"));
driver.findElement(By.xpath("//button[contains(., 'Sign in')]")).click();
wait.until(urlContains("/dashboard"));
assertEquals("Welcome back, admin!",
driver.findElement(By.cssSelector(".greeting")).getText());
```
```ts title="e2e"
import { test } from '@e2e-dev/web';
import { expect, credentials } from 'e2e';
test('signs in', async ({ app, screen, browser }) => {
const admin = credentials.user('admin');
await app.open('/login');
await screen.getByLabel('Username').fill(admin.username);
await screen.getByLabel('Password').fill(admin.password);
await screen.getByRole('button', 'Sign in').tap();
await expect(browser).toHaveURL('/dashboard');
await expect(screen.getByRole('status')).toHaveText('Welcome back, admin!');
});
```
## Map each WebDriver call
| Selenium | e2e |
| --- | --- |
| `driver.get(url)`, `navigate().back()`, `.forward()`, `.refresh()` | `app.open(path)`, `app.back()`, `browser.forward()`, `browser.reload()` |
| `getCurrentUrl()`, `getTitle()`, `manage().addCookie`, `getScreenshotAs` | `browser.url()`, `browser.title()`, `browser.setCookies`, `app.screenshot('label')` |
| `By.id('x')` | `browser.locator('#x')`, or `'[id="x"]'` when the id has `:`, `.`, `$`, or a leading digit |
| `By.name`, `By.cssSelector`, `By.xpath` | `browser.locator('[name="x"]')`, `browser.locator('css or xpath')` |
| `By.linkText`, `By.partialLinkText` | `screen.getByRole('link', { name })`, `name: /part/` |
| `findElements(...).size()`, `.get(n)` | `await locator.count()`, `locator.nth(n)` |
| `.click()`, `.clear()`, `Actions.moveToElement`, `Actions.dragAndDrop` | `.tap()`, `.clear()`, `.hover()`, `.dragTo(target)` |
| `.sendKeys('text')` | `.fill('text')` replaces the content, `.pressSequentially('text')` appends |
| `.sendKeys(Keys.ENTER)`, `Actions.keyDown(CONTROL).sendKeys('a')` | `.press('Enter')`, `.press('ControlOrMeta+a')` |
| `.sendKeys(path)` on a file input, `new Select(el).selectByVisibleText` | `.setInputFiles(path)`, `.selectOption({ label })` |
| `.getText()`, `.isDisplayed()`, `.getDomAttribute(name)` | `.textContent()`, `.isVisible()`, `.getAttribute(name)` |
| `.getAttribute('value')`, `.getAttribute('checked')` | `.inputValue()`, `.isChecked()`. e2e's `.getAttribute()` reads the DOM attribute, not the property |
| `wait.until(visibilityOf(...))`, `textToBe(...)`, `urlContains(...)` | `expect(locator).toBeVisible()`, `.toHaveText(...)`, `expect(browser).toHaveURL(/.../)` |
| `switchTo().frame()`, `switchTo().alert().accept()` | `browser.frameLocator('#frame')`, `browser.onDialog('accept')` before the action |
| `switchTo().window(handle)`, `getWindowHandles()`, `switchTo().newWindow()` | `tab.activate()`, `browser.tabs()`, `browser.newTab()`; `browser.waitForPopup(() => trigger)` for a tab the app opens, see [Tabs](/reference/web#tabs) |
| `executeScript(script, args)` | `browser.evaluate(fn, arg)`, JSON in and out only |
| Page objects | A fixture from `test.extend`, or a goal for `agent.act`, see [Page objects](/page-object-model) |
## What e2e doesn't have yet
Planned means on the roadmap, and Not yet means no date. Not planned means
e2e leaves it out on purpose.
### Planned
| Selenium | Use today |
| --- | --- |
| `executeScript(script, element)`, `getDomProperty`, `getCssValue` | A locator action such as `.tap()` or `.scrollIntoView()`, or `browser.evaluate` with a CSS selector |
| `element.findElement(By.cssSelector)`, WebdriverIO `$('a').$('b')` | One `browser.locator('a >> b')` selector, or chained `getBy*` queries |
| `ChromeOptions.addArguments`, `setBinary`, `Proxy`, `acceptInsecureCerts` | Start Chrome or Edge with the flags, then attach with `web({ connect })` |
| `@BeforeSuite`, `@AfterSuite`, pytest session-scoped fixtures, WebdriverIO `onPrepare` | Once for the run: the script `app.command` starts, or a wrapper around `e2e run`. Once for a file: `beforeAll` and `afterAll`. Sign-in: a top-level `test.setup` that saves a session |
| BrowserStack or Sauce Labs for web | Your own [browser provider](/browser#write-a-provider), if the vendor has a CDP endpoint |
| `manage().logs()`, request listeners, geolocation | Patch the page in `browser.addInitScript`, record requests in `browser.route` |
| `setNetworkConditions` | For offline, abort requests in `browser.route`. No throttling or latency, keep those tests in Selenium |
### Not yet
| Selenium | Use today |
| --- | --- |
| `new RemoteWebDriver(gridUrl)`, Firefox or Safari on remote nodes | `web({ connect })` to a CDP endpoint. Run `firefox` and `webkit` targets locally |
| Two drivers in one test, WebdriverIO `multiremote` | Drive the second user through the app's API |
| `getPageSource()`, `getLocalStorage()`, `getSessionStorage()` | `browser.evaluate`, such as `() => localStorage.getItem('k')` |
| Java, Python, C#, or Ruby bindings | Tests are TypeScript or JavaScript |
### Not planned
| Selenium | Use instead |
| --- | --- |
| Cucumber feature files | Rewrite each scenario as a test. A step often fits one `agent.act` goal |
| `Thread.sleep`, `Actions.pause`, `wait.until(elementToBeClickable(...))` | A locator assertion on the state you wait for. Each action waits for its node |
| `switchTo().alert()` after the dialog opens, `alertIsPresent()` | `browser.onDialog(handler)` before the action that opens it |
| Real Safari, IE mode | `webkit` is the closest build to Safari. Keep IE mode tests in Selenium |
| `executeCdpCommand`, `DevTools.send`, SDKs that take the driver | Keep those tests in Selenium. A raw driver call isn't recorded or redacted |
| Allure reports | Feed the `junit` reporter's XML to Allure, or use `htmlReporter()` |
## What differs on purpose
- `findElement` takes the first match. e2e fails with `LOCATOR_AMBIGUOUS` on
several, so narrow with `.filter()`, `.first()`, or `.nth()`.
- There is no implicit wait. Actions and assertions wait on their own, up to
`actionTimeout` and `assertionTimeout`.
- Each test gets a fresh browser context, not a shared driver. To sign in one
time, use `test.setup` and `{ session }`, see [Authentication](/authentication).
- The page size comes from `web({ viewport })`, not `setSize` or `maximize()`.
## Next
<CardGroup cols={2}>
<Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
Goals, assertions, and locators instead of scripted selectors.
</Card>
<Card title="screen reference" icon="crosshairs" href="/reference/screen">
Every query, refinement, action, and read.
</Card>
</CardGroup>