> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/export-import-and-backup/import-export.md).
# Overview
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.
{% hint style="info" %}
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.
{% endhint %}
### 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:
```yaml
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](/export-import-and-backup/importing.md). 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/
├── 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
```
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.
{% hint style="warning" %}
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.
{% endhint %}
***
### Availability
Using the [Public API](/integrations/public-api.md) requires API access, which is available on paid plans.
{% hint style="success" %}
Export and import are available on every plan, including FREE.
{% endhint %}
***
### Related pages
* [Exporting](/export-import-and-backup/exporting.md): download files from the app or API and keep them in Git
* [Importing](/export-import-and-backup/importing.md): bring files back and resolve conflicts
* [YAML schema](/export-import-and-backup/yaml-schema.md): 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.bugbug.io/export-import-and-backup/import-export.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.