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 and currently supports Claude Code.

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.

Prerequisites

• Node.js 18 or newer

• 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

1

Install the wizard into your project

In the root folder of your test project run:

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.

2

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:

npx @cloudbeat/cli login

For a self-hosted CloudBeat installation add --apiBaseUrl https://<your CloudBeat API address>.

3

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.

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.

.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.

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.