> For the complete documentation index, see [llms.txt](https://docs.cloudbeat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudbeat.io/cloudbeat-playwright-integration-migration-guide.md). # CloudBeat Playwright Integration - Migration Guide This guide describes the changes required to your Playwright project in order to support the latest CloudBeat execution engine. These updates enable **individual test execution** (instead of whole-spec only), **nested folder support**, **improved result reporting**, and **greater overall flexibility**. *** ### 1. Update `@cloudbeat/playwright` to v2.1.0 Update the package to the latest version using one of the following commands, depending on how it is installed in your project: **Regular dependency:** ```bash npm install --save @cloudbeat/playwright ``` **Dev dependency:** ```bash npm install --save-dev @cloudbeat/playwright ``` After updating, verify your `package.json` reflects version `2.1.0` or higher. If you are using Git, make sure to commit the updated `package-lock.json` as well. *** ### 2. Update `@playwright/test` to v1.56.0 or Later *(Optional)* This step is optional but **strongly recommended** if your test suite contains tests with **Hebrew or other special characters** in their names (e.g. accented letters, symbols, etc). Upgrading ensures more reliable test execution in those cases. **Dev dependency:** ```bash npm install --save-dev @playwright/test@1.56.0 ``` *** ### 3. Ensure Commands Run Successfully on an External Server When a project is uploaded manually or synchronized from Git, CloudBeat executes the following two commands on its server: ```bash npm ci npx -y playwright test .spec.ts --list ``` **Both commands must complete successfully in a clean, external environment.** To verify this, make sure your project: * Does **not** rely on any files that only exist on your local machine (note: dynamic imports inside test bodies are fine, as long as `npx -y playwright test .spec.ts --list` completes successfully - that command does not execute the tests themselves) * Does **not** depend on packages from **private registries or repositories** (unless the server is configured to access them) * Has a valid and complete `package-lock.json` committed to the repository (required by `npm ci`) * Has all required environment variables documented, with safe defaults where possible Test this locally by cloning your repo into a fresh directory and running both commands from scratch. *** ### 4. Remove Line Breaks from Test Titles Test titles must **not contain line breaks** (`\n`). Tests with multi-line titles will not be executed correctly. This issue most commonly occurs when using template literals (backtick strings) in JavaScript/TypeScript. Make sure all test titles are on a single line. **❌ Incorrect — contains a line break:** ```js test(`user can log in with valid credentials`, async ({ page }) => { // ... }); ``` **✅ Correct — single line:** ```js test(`user can log in with valid credentials`, async ({ page }) => { // ... }); ``` Review your entire test suite for any `test(...)` or `describe(...)` blocks where the title string spans multiple lines, and flatten them. *** ### 5. Manually Added Cases Will Be Cleared on Project Re-upload/Re-Sync > ⚠️ **Important:** Any test cases that were manually added to suites in CloudBeat will be **removed** when the project is re-uploaded/re-synced first time. After completing the migration and re-uploading your project, make sure to **re-add test cases** to their respective suites. *** ### Summary of Required Changes
#ChangeRequired
1Update @cloudbeat/playwright to 2.1.0+✅ Yes
2Update @playwright/test to 1.56.0+⚠️ Optional (but highly recommended)
3Ensure npm ci and --list commands succeed on a clean server✅ Yes
4Remove line breaks from all test titles✅ Yes
5Re-add manually added cases after re-upload/re-sync⚠️ Informational