> 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/get-started/ai-assisted-project-setup.md). # AI-Assisted Project Setup Connect an existing test automation project to CloudBeat with the help of an AI coding agent If you want to add your existing test automation project to CloudBeat, an AI coding agent can do the CloudBeat integration and onboarding for you: it installs and configures the CloudBeat Kit for your framework, creates the project in CloudBeat, and delivers your code to it, either through Git integration or by uploading it. You review and approve every change before it is made. The wizard is part of the [CloudBeat CLI](/references/cloudbeat-cli.md) and currently supports [Claude Code](https://claude.com/claude-code). {% hint style="info" %} The wizard replaces the manual "Connect your test project to CloudBeat" steps described on the framework pages. Everything it does can also be done by hand, using the CloudBeat UI and the CLI. {% endhint %} ## Prerequisites * [Node.js](https://nodejs.org) 18 or newer * [Claude Code](https://claude.com/claude-code) installed and signed in * A CloudBeat account and your API key (found in your CloudBeat user profile) * Your test project, ideally cloned from its Git repository ## Setup {% stepper %} {% step %} ### Install the wizard into your project In the root folder of your test project run: ```bash npx @cloudbeat/cli init --agent claude ``` This adds the `/cloudbeat`, `/cloudbeat-kit` and `/cloudbeat-sync` commands and the `cloudbeat-setup` skill to the `.claude` folder of your project. Files you edited locally are never overwritten unless you pass `--force`. {% endstep %} {% step %} ### Log in to CloudBeat The wizard never asks for secrets in the chat. Store your API key once with the CLI - the key is entered with hidden input and saved on your machine only: ```bash npx @cloudbeat/cli login ``` For a self-hosted CloudBeat installation add `--apiBaseUrl https://`. {% endstep %} {% step %} ### Run the wizard Open Claude Code in the same folder and type: ``` /cloudbeat ``` The wizard detects your stack, asks a few questions, shows a plan, and continues only after you approve it. When it finishes, your project exists in CloudBeat and the first synchronization has run. {% endstep %} {% endstepper %} ## What the wizard does The wizard works in phases and saves its progress in `.cloudbeat/setup.md`, so it can be interrupted and resumed with `/cloudbeat`. 1. **Connect** - checks that the CLI is available and that you are logged in. 2. **Detect** - finds your language, test framework, automation library, build tool and where the WebDriver or browser is created, and asks you to confirm. 3. **Kit options** - offers only the features your framework's kit supports (see the table below). Choose *Use recommended settings* to accept the defaults. 4. **Plan** - shows every dependency it is about to add and every file it is about to change, with the exact diff. **Nothing is written before you approve.** 5. **Install** - applies the plan and verifies that the project still compiles or lists its tests. It does not run your tests. 6. **CloudBeat project** - lets you create a new project or choose an existing one of the matching type. 7. **Code delivery** - Git integration when your project has a Git remote, otherwise a file upload (see below). 8. **Wrap-up** - a summary of what changed, and what is left for you to do, such as committing the kit changes. ### Kit features by framework | Framework | Kit installed by the wizard | Optional features it offers | | ------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Playwright (JS/TS) | `@cloudbeat/playwright` reporter | Browser console logs, screenshots, video and trace on failure | | Playwright with Cucumber.js | `@cloudbeat/cucumber` formatter | Playwright page and `expect` wrapping (actions as sub-steps), browser console logs, video and trace attachments | | Java - TestNG, JUnit 5 (also Kotlin) | `cb-kit-testng` / `cb-kit-junit5`, plus `cb-kit-selenium4` for Selenium 4 and Appium | WebDriver wrapping (actions as steps, screenshots and browser logs), network capture as HAR on Chromium, use of the browser selected in CloudBeat, RestAssured reporting (TestNG), console capture, `@CbStep` annotations | | .NET - NUnit, MSTest | `CloudBeat.Kit.NUnit4` / `CloudBeat.Kit.NUnit` / `CloudBeat.Kit.MSTest` (+ `CloudBeat.Kit.Playwright`) | WebDriver wrapping, page source on failure, NLog forwarding, `HttpClient` reporting, `[CbStep]` attributes | | Python - Pytest | `cloudbeat-pytest`, plus `cloudbeat-selenium` for Selenium | WebDriver wrapping, `@cb.step` decorators | | Cypress | None needed - CloudBeat adds its reporter at run time | - | All kits stay inactive when the tests run outside CloudBeat, so local and CI runs are not affected. ### Code delivery **Git integration** - the wizard reads the repository URL and branch from your working copy and asks you to confirm them. SSH addresses are converted to HTTPS, because CloudBeat authenticates with an access token. It warns about commits that are not pushed yet, including the kit changes it has just made: CloudBeat only sees what is on the remote. For a private repository you choose when to provide the credentials: * **Now** - you run the project creation command yourself in the terminal; the CLI asks for the access token with hidden input. A read-only token is enough. * **Later** - the project is created with the URL and branch only. The first synchronization fails with an authentication error, which is expected. Enter the credentials in the project settings in CloudBeat and run `/cloudbeat-sync`. * **Not needed** - for public repositories. **File upload** - when the project has no Git remote, the wizard packs the folder and uploads it. `.gitignore` is honored, and you can exclude more with a `.cbignore` file in the project root. `node_modules`, `.git`, `.env` files and private keys are never uploaded. After code changes, run `/cloudbeat-sync` to upload again. {% hint style="warning" %} .NET projects are delivered as compiled binaries. The wizard builds the test project and uploads its build output; Git integration is not available for .NET project types. {% endhint %} ## Later on * `/cloudbeat-sync` - trigger a Git synchronization, or pack and upload the current code again, and report the result. * `/cloudbeat-kit` - install the kit into a project without creating a CloudBeat project, or change kit options later. Only the differences are applied. * `/cloudbeat restart` - run the whole setup again, ignoring the saved state. The `.cloudbeat/setup.md` state file and the `.claude` folder contain no secrets and can be committed, so that teammates can use `/cloudbeat-sync` and `/cloudbeat-kit` too. Neither folder is ever uploaded to CloudBeat. ## Security * Your API key and Git credentials never pass through the conversation with the agent: they are entered in the terminal with hidden input, and the API key is stored in `~/.cloudbeat/config.json`, readable by your user only. * The agent changes only build files, test configuration and the test bootstrap code named in the plan - never your test logic - and only after you approve the plan. * Every CloudBeat operation goes through the CLI; the agent does not call the CloudBeat API directly. ## Troubleshooting | Symptom | What to do | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `whoami` reports `not_logged_in` | Run `npx @cloudbeat/cli login`. With a self-hosted installation, add `--apiBaseUrl`. | | The first Git synchronization failed with an authentication error | Expected when you chose to provide credentials later. Add them in the project settings in CloudBeat and run `/cloudbeat-sync`. | | Synchronization failed with a branch error | The branch is not on the remote yet: push it and run `/cloudbeat-sync`. | | The wizard says a kit artifact is not available | The kit cannot be installed from a public package repository in your setup. The wizard continues without the kit - tests still run and report results, without action steps and screenshots. Contact CloudBeat support for the kit. | | Claude Code does not offer `/cloudbeat` | Make sure you opened Claude Code in the folder where you ran `init`, and that `.claude/commands/cloudbeat.md` exists. |