# 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

<table><thead><tr><th width="40">#</th><th width="385">Change</th><th>Required</th></tr></thead><tbody><tr><td>1</td><td>Update <code>@cloudbeat/playwright</code> to <code>2.1.0+</code></td><td>✅ Yes</td></tr><tr><td>2</td><td>Update <code>@playwright/test</code> to <code>1.56.0+</code></td><td>⚠️ Optional (but highly recommended)</td></tr><tr><td>3</td><td>Ensure <code>npm ci</code> and <code>--list</code> commands succeed on a clean server</td><td>✅ Yes</td></tr><tr><td>4</td><td>Remove line breaks from all test titles</td><td>✅ Yes</td></tr><tr><td>5</td><td>Re-add manually added cases after re-upload/re-sync</td><td>⚠️ Informational</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cloudbeat.io/cloudbeat-playwright-integration-migration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.