> 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/organizing-tests-with-folders.md).
# Organizing tests with folders
Folders let you group related tests inside a project, so hundreds of tests stay navigable. You can nest folders, move tests between them, and the structure is preserved when you export or import your project as YAML.
> Folders for [components](/editing-tests/components.md#organizing-components-with-folders) are documented separately.
### Overview
Every project has a **Home** level. Tests live either directly in Home or inside a folder. A folder can contain both tests and other folders.
Key rules:
| Rule | Value |
| ------------------------- | ------------------------------------------- |
| Maximum nesting depth | 5 levels below Home |
| Items allowed in a folder | Tests and subfolders |
| Folder name uniqueness | Must be unique among siblings (same parent) |
| Tests per folder | Unlimited |
A test always belongs to exactly one folder. Moving a test between folders does not change its ID, its history, or its membership in any suite or schedule.
***
### The two views
The **Tests** screen has two tabs that display the same tests in different layouts.
#### Folders (default)
A hierarchical view that shows one folder at a time: the subfolders and tests directly inside the folder you are currently in. A breadcrumb at the top (`Home / Company profile / ...`) shows where you are and lets you jump back up a level.
Folder rows show `—` in the **Screen size** and **Last result** columns, since those values only apply to tests.
Use this view when you are working inside one area of your application and want the rest of the project out of the way.
#### All tests
A flat list of every test in the project, regardless of where it sits. Each row shows the full path of the test underneath its name, for example `/App/Billing/` or `/Landing`. Tests that are not in any folder show `/` as their location.
Use this view when you want to see everything at once, or when you are looking for a test but do not remember where it lives.
***
### Creating a folder
1. Open the **Tests** screen.
2. Navigate to the level where the folder should be created. The new folder is always created inside the folder you are currently viewing.
3. Click on the right side of the page
4. Enter a name and confirm.
If you are already 5 levels deep, you have reached the maximum nesting depth.
***
### Moving tests into a folder
1. Select one or more tests using the checkboxes on the left of the list.
2. Choose **Move to folder** () from the bulk actions.
3. Pick the target folder from the folder tree, or pick **/ (home)** to move tests out of all folders.
You can move tests from either view. Moving a folder moves everything inside it; if the move would push any nested folder past the 5-level limit, the operation is rejected, and nothing is moved.
***
### Renaming and deleting folders
Open the Actions menu on a folder to rename or delete it.
**Renaming** only affects the display path. Test IDs and run history are untouched.
**Deleting an empty folder** happens immediately.
{% hint style="danger" %}
**Deleting a folder deletes the tests inside it.** If you only want to remove the grouping, move the tests to Home first, then delete the empty folder.
{% endhint %}
***
### Search, filters, and sorting
Search, the status and screen size filters, and the sort selector all work with folders.
**In the Folders view**, they apply recursively from the folder you are currently in. As soon as a search term or filter is active, the list switches to a flat result list showing the full path of each match, so you can see where the results actually live. Folders that contain no matching tests are hidden from the results. Clearing the search returns you to the normal hierarchical view at the same location.
**In the All tests view**, they behave as they always have and apply to the whole project.
**Sorting** orders folders and tests together in a single list using the selected criterion. Because folders have no screen size or last result, sorting by those values places folders at the end of the list.
### Frequently asked questions
Does moving a test to a folder break my suites, schedules, or CI runs?
No. Folders are an organizational layer only. Suites, schedules, alerts, and CLI or API runs reference tests directly and are unaffected by where a test sits.
Can I run every test in a folder at once?
Not directly - folders are not a run target. Use a suite if you want to execute a group of tests together.
What happens to tests I created before folders existed?
They stay at Root level. Nothing changes until you move them.
Why can I not create another subfolder?
You are at the 5-level limit. Move the content up a level, or flatten part of the structure.
---
# 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/organizing-tests/organizing-tests-with-folders.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.