Importing

Bring BugBug tests and projects back in from YAML, and resolve conflicts when something already exists.

Import a test

1. Go to the Tests screen.

2. Open the Actions menu in the top right.

3. Choose Import test.

4. Upload a .yaml or .zip file.

The test is added to the project you are currently viewing. A test ZIP also imports the components it contains.

---

When something already exists

BugBug matches incoming tests and components to existing items by slug. If it finds a match, the import pauses and shows the differences.

The modal shows the current and incoming YAML side by side. Review the changes, then choose:

Choice	Effect
Overwrite all	Replace the existing test and components with the incoming ones.
Skip existing	Keep what you have. Anything in the file that does not exist yet still gets imported.
Cancel	Nothing is imported.

If the two versions are identical, BugBug reports that instead of showing an empty diff.

---

When a component is missing

A test exported as YAML refers to its components by slug instead of including them. If the target project does not have one of those components, BugBug cannot build the test as written.

By default the import stops and names the missing component. You can import the test as a ZIP, or import the project that contains the component first.

---

Import a whole project

1. Go to your project list.

2. Open the Actions menu next to the page title.

3. Choose Import BugBug ZIP.

4. Upload a project .zip.

A project import always creates a new project. It never merges into an existing one and never overwrites a project you already have. If you want to update an existing project, import the individual tests instead.

The archive is imported as a new project, so there are no conflicts with an existing project. The new project appears in your list when the import finishes.

---

Import with the CLI

You can import a project ZIP or a test YAML/ZIP from the terminal. See the BugBug CLI for the commands and authentication options.

bugbug project import accepts project ZIP files. bugbug tests import accepts test YAML or ZIP files.

---

Import through the API

A test

Import a test

curl -X POST \
  -H "Authorization: Token <api-token>" \
  -F "file=@test_login.yaml" \
  "https://api.bugbug.io/v2/tests/import/"

Two optional query parameters control conflict handling and missing components:

Parameter	Values	Default	Meaning
conflictMode	overwrite, skip	none	Decide up front what to do about slugs that already exist.
onMissingComponent	error, skip	error	skip imports the test without the steps that use the missing component.

If you omit conflictMode and a conflict is found, BugBug writes nothing and returns 200 with the conflict details:

{
  "status": "conflict",
  "entityIds": {},
  "conflicts": [
    {
      "entityType": "test",
      "slug": "login-with-valid-credentials",
      "name": "Login with valid credentials",
      "existingId": "0b8f...",
      "yamlDiff": {
        "currentYaml": "...",
        "incomingYaml": "..."
      }
    }
  ]
}

Pass ?conflictMode=overwrite or ?conflictMode=skip to resolve conflicts in the same request.

A newly created, updated, or skipped test returns 201. If conflictMode is omitted and a slug conflict is found, the request returns 200 with status: conflict and the conflict details instead of writing anything. In each case entityIds lists the entities written; a skipped test has an empty list.

To inspect a file before importing it, post it to /v2/tests/import/check/. This endpoint does not write anything and can be called repeatedly:

{
  "valid": true,
  "summary": {
    "tests": 1,
    "components": 3
  }
}

The check confirms that the file is a well-formed test export. It does not compare the file with your project, so a passing check does not guarantee that the import will succeed.

View test import endpoints

A project

A project import over the API takes two calls. You can also check the archive first.

Optional check. Post the archive to /v2/project/import/check/ to validate it without storing anything. You can call this endpoint repeatedly:

Check a project archive

curl -X POST \
  -H "Authorization: Token <api-token>" \
  -F "file=@project_shop.zip" \
  "https://api.bugbug.io/v2/project/import/check/"

{
  "valid": true,
  "summary": {
    "tests": 42,
    "components": 8,
    "suites": 3,
    "profiles": 2
  }
}

The check confirms that the archive is a well-formed project export. It does not compare the archive with your organization, so a passing check does not guarantee that the import will succeed.

Step 1 - validate and upload:

Validate and upload a project archive

curl -X POST \
  -H "Authorization: Token <api-token>" \
  -F "file=@project_shop.zip" \
  "https://api.bugbug.io/v2/project/import/validate/"

{
  "uploadId": "3f2a...",
  "summary": {
    "tests": 42,
    "components": 8,
    "suites": 3,
    "profiles": 2
  }
}

Use the summary to confirm that the archive contains what you expect. The uploadId is valid for 30 minutes.

Step 2 - run the import:

Start the project import

curl -X POST \
  -H "Authorization: Token <api-token>" \
  -H "Content-Type: application/json" \
  -d '{"uploadId": "3f2a..."}' \
  "https://api.bugbug.io/v2/project/import/run/"

{
  "projectId": "9c41...",
  "status": "pending"
}

The endpoint returns the ID of the new project immediately. Larger archives may continue importing in the background.

View project import endpoints

---

When an import is rejected

A test import runs in a single transaction. If the file is rejected or the import fails, the project stays unchanged.

What went wrong	Example message
No file in the request	No file provided
Upload over the size limit	File too large
Wrong file type for a project import	Project import requires a .zip file
The YAML is not a valid BugBug document	Missing 'schema_version' field in YAML envelope
The YAML is the wrong kind of document	Expected test YAML, got component
The archive is not a usable export	ZIP does not contain a test YAML file, ZIP contains multiple test files, ZIP does not contain a project.yaml file
The archive failed a safety check	Path traversal in ZIP: ..., Symlink in ZIP: ..., Suspicious compression ratio for ...
A referenced component is unavailable	Component "goto-bugbugio" is not available in this project. Try to export the test as a ZIP file containing components as well.
The upload slot expired	Invalid or expired uploadId

Before BugBug reads an archive, it checks for path traversal, symlinks, encrypted entries, and implausible compression ratios. These checks prevent an untrusted archive from writing outside the import.

If a file will not import, checking it against the YAML schema can help locate the problem.

---

Frequently asked questions

Can I import a project into an existing project?

No. Project import always creates a new project. To update an existing project, import tests individually.

What happens to run history when I import a test over an existing one?

Overwrite replaces the definition. The test keeps its identity and past runs.

Can I import a file I wrote by hand?

Yes, provided it validates against the YAML schema and uses the document type and format accepted by the import route. A standalone import accepts a test YAML document; the other document types need to be included in the appropriate ZIP export.

Can I import from the CLI?

Yes. The CLI can import project ZIP files and test YAML or ZIP files. See Import with the CLI.

Does importing a test add it to my suites?

No. Add it to a suite after the import, or import a project ZIP, which includes suite membership.