Overview

Move your tests, components, suites and profiles in and out of BugBug as plain text. No vendor lock-in - the files are yours to keep, version and review.

BugBug exports tests, reusable components, suites, profiles, and project settings as plain text. You can read the YAML, review changes in a diff, and keep the files with the rest of your code.

The files remain readable outside BugBug, too.

ZIP exports contain BugBug YAML files together with any required artifacts.

BugBug YAML describes what a test does. It is a test definition, not executable code. A YAML file will not run on its own in Playwright, Cypress, or Selenium. Import it into BugBug, then run the test locally, in the cloud, or from your CI pipeline.

Available exports and imports

What	Export	Import
A single test	YAML or ZIP	YAML or ZIP, into an existing project
A whole project	ZIP	ZIP, always as a new project
Components, suites, profiles	Inside a project ZIP	Inside a project ZIP

Components, suites, and profiles cannot be exported on their own. They are included in a project ZIP. Components are also included in a test ZIP when the test uses them.

---

YAML and ZIP

YAML is one file containing one item. A test YAML contains the test's steps and settings. If the test uses a reusable component, the file refers to it by name instead of including a copy:

groups:
- component_source: goto-bugbugio
- group_name: Simple steps
  slug: simple-steps
  steps:
  - action: click
    action_details:
      selector: xpath=//SPAN[normalize-space(text())="Log in"]

This keeps the YAML small and readable. It also means that importing the file into a project without the goto-bugbugio component needs an extra decision. See Importing. Files used by the test are referenced in the same way, so a YAML export does not include them.

ZIP is a bundle. It contains the exported item, its dependencies, and the files used by its steps, such as upload attachments and visual regression baselines.

Use YAML for a single test that you want to review or attach to a pull request. Use ZIP when the test or project needs to arrive with its dependencies and files.

---

Project ZIP contents

your-project/
├── bugbug-export.json    what produced this archive: BugBug version, date, source project
├── project.bugbug.yaml   project settings, selectors, waiting conditions, screen sizes
├── tests/                one file per test
├── components/           one file per reusable component
├── suites/               one file per suite
├── profiles/             one file per profile
└── artifacts/            files your tests use: upload attachments, visual regression baselines

{
  "format_version": 1,
  "generator": { "product": "bugbug", "version": "14.1.0" },
  "created_at": "2026-09-03T09:12:44+00:00",
  "export": {
    "type": "project",
    "origin": "webapp",
    "source_project_id": "f50110d2-ba04-48f1-8d5b-ab24b9df6138",
    "schema_version": "1.0"
  },
  "contents": { "tests": 12, "components": 4, "suites": 2, "profiles": 1 }
}

format_version describes the archive layout itself, separately from the per-file schema_version. Import reads bugbug-export.json first and refuses an archive whose format_version is newer than the BugBug you are importing into understands - this only happens with an archive created on a newer BugBug deployment. Archives exported before this file existed still import.

The tests/ and components/ directories follow the folder structure from the app:

tests/
├── Auth/
│   └── Login/
│       └── login-with-valid-credentials.bugbug.yaml
├── Billing/
│   └── upgrade-plan.bugbug.yaml
└── smoke-test.bugbug.yaml

Directories use the folder names from the app. Each test or component file uses its slug followed by .bugbug.yaml. Folders with a description also contain a small .folder.yaml file. Folders without a description do not have a marker file.

---

How imports identify items

BugBug identifies each item by its slug. A slug is a short, lowercase, URL-friendly name generated from the display name when the item is created. A test named Login with valid credentials gets the slug login-with-valid-credentials.

Files use slugs in references such as component_source and test_source. Import also uses them to find existing items:

• A slug stays the same after the item is created. Renaming a test changes its display name but not its slug. A test renamed to Sign in may therefore still have the slug login-with-valid-credentials. An older export can then update that test instead of creating a duplicate.

• Slugs are unique within a project. Two projects can use the same slug without affecting each other.

If you edit an exported file by hand, treat the slug as the item's identity and the name as its label.

For a test or component, changing the slug makes the next import create a separate item. Changing the name keeps the same identity. The new name is applied only if you overwrite the item when the import reports a conflict. If you skip the conflict, BugBug ignores the file, including its name.

Suites, profiles, and project settings are handled differently. They are imported only with a project ZIP, and a project import always creates a new project. BugBug does not match or rename those items during import.

---

Availability

Using the Public API requires API access, which is available on paid plans.

Export and import are available on every plan, including FREE.

---

Related pages

• Exporting: download files from the app or API and keep them in Git

• Importing: bring files back and resolve conflicts

• Automatic backups: daily project backups on paid plans, and how to restore one

• YAML schema: the file format, validation, and editor autocomplete

FAQ

Can I import and export my BugBug tests?

Yes. Export individual tests as human-readable YAML for review, editing, and version control. For a complete backup, including components and required files, export your test or project as a ZIP. Your test assets aren’t locked inside BugBug.

What can I import and export from BugBug?

You can export a single test as YAML or as a ZIP containing its components and required files. A full project export includes tests, components, suites, profiles, settings, folders, and test artifacts.

Can I review and version BugBug tests outside the platform?

Yes. BugBug tests are exported as human-readable YAML, so you can inspect changes, review diffs, and store them in Git. YAML files describe the test but are not directly executable in Playwright, Cypress, or Selenium.

What happens if an imported test already exists?

BugBug identifies matching tests and components by their slug and shows the differences before making changes. You can overwrite the existing version, skip it, or cancel the import.