> 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/organizing-tests/files.md).

# Files

Keep the files used by upload steps in one place, organize them in folders, and reuse them across tests.

**Files** is the project library of files used by [Upload file](https://docs.bugbug.io/editing-tests/actions.md#upload-file) steps. Every file uploaded while recording a test, in the step details, or through the API lands here, so you can find it, preview it, and reuse it in other tests instead of uploading the same file again.

Open it from the project menu: **Files**.

### What you can do

| Action           | How                                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Upload new files | Click **Upload new**, then drag and drop files or browse your disk. Files are uploaded to the folder you are currently viewing.                              |
| Preview a file   | Click a file row. Images, PDFs, XLS/XLSX spreadsheets, DOC/DOCX documents, video, audio, and text files (for example CSV, JSON, TXT) are previewed in place. |
| Download a file  | Click **Download** in the file row or in the preview.                                                                                                        |
| Rename a file    | Open the row actions menu (**⋯**) and choose **Rename**. The file extension is kept.                                                                         |
| Move files       | Choose **Move to folder** from the row actions menu, or select several rows and use the bulk actions.                                                        |
| Remove files     | Choose **Remove** from the row actions menu, or select several rows and use the bulk actions.                                                                |
| Find files       | Search by name, filter by **Extension**, and sort by date created, name, extension, or size.                                                                 |

{% hint style="info" %}
Each file can be up to **10 MB**. Each project can store up to **1,000 files**, including files uploaded while recording. Logs, reports, backups, and visual regression screenshots do not count toward this limit.
{% endhint %}

Files stay in the library until you remove them, even when no step uses them. Replacing a file in a step keeps the previous library file available for reuse.

### Folders

Files support their own folders, separate from [test folders](https://docs.bugbug.io/organizing-tests/organizing-tests-with-folders.md). Switch between the **Folders** and **All files** views, create nested folders with **New folder**, and move files or folders between them. In the **All files** view each file shows its folder path. Searching or filtering by extension always lists matching files from all folders.

Folders are available on paid plans. Removing a folder removes the files inside it.

### Use a file in an upload step

In the step details of an **Upload file** step, click **Select file** (or drop a file onto the field). Pick an existing file on the **Files library** tab, or upload a new one on the **Upload new** tab (it is saved to Files). Confirm with **Use this file**. The same file can be used by any number of steps and tests. To preview the file, click its name in the step details or the eye icon next to the step in the steps list.

While recording, BugBug shows a **File upload recorded** panel right after you upload a file on the tested page. Pick a file from the list (files with the same name are shown first) to use it instead of the one from your disk, or click **Keep uploaded file**.

Duplicating a test or a step reuses the same file. Copying a project copies all of its files and folders.

Full project ZIP exports include the Files library, including unused files and empty folders. Files in folders keep their hierarchy under `artifacts/files/`; for example, `Invoices/2026/invoice.csv` is exported as `artifacts/files/Invoices/2026/<short-artifact-id>/invoice.csv`. The ID directory distinguishes files with matching names and keeps the original filenames intact. Importing the ZIP restores the folder hierarchy and file assignments. Individual test ZIP exports preserve the folders of the files used by that test.

### Use a file as the microphone or camera

The **Media source** step also picks its file from here, filtered to the supported formats: WAV, MP3, OGG, M4A or FLAC for the microphone, WebM or MP4 for the camera. The same files can be set as the camera and microphone of a project or a test, see [Camera & microphone](https://docs.bugbug.io/editing-tests/faking-camera-and-microphone.md). Keep your audio and video samples in a folder to reuse them across tests. See [Media source](https://docs.bugbug.io/editing-tests/actions.md#media-source).

### Removing a file used by steps

The remove dialog shows how many upload steps use the file and in which tests. The steps are kept after the file is removed, but they fail until you choose another file for them.

### Automate with API, CLI, SDK, and MCP

* **Public API** — `GET/POST /api/v2/projects/{projectId}/files/` and `GET/PATCH/DELETE /api/v2/projects/{projectId}/files/{fileId}/`, plus `download/`, `usage/`, `bulk-move/`, `bulk-delete/`, and `extensions/`. See [Public API](https://docs.bugbug.io/integrations/public-api.md).
* **CLI** — `bugbug files list | upload | rename | move | download | delete`. See [CLI](https://docs.bugbug.io/integrations/cli.md).
* **SDK** — the `files` module. See [TypeScript SDK](https://docs.bugbug.io/integrations/typescript-sdk.md).
* **MCP** — the `bugbug_files_*` tools. See [MCP tools](https://docs.bugbug.io/ai-testing/mcp/mcp-tools.md#files).

Use the file ID as `projectArtifactId` when you create an `uploadFile` step through the API, SDK, or MCP.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/organizing-tests/files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
