> 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/editing-tests/components.md).
# Components
Reusable groups of steps shared across tests: making, inserting, editing, unlinking, splitting, removing and deleting components, passing different values with variables, and working with components t
A component is a [group of steps](/editing-tests/grouping-steps.md) that is shared by many tests. A typical example is logging in: record it once, make it a component, and insert it into every test that needs a signed-in user.
When you change a component, the change applies to every test that uses it. If your login form gets a new selector, you fix it once instead of in every test.
{% hint style="info" %}
**In short**
* A component is a group that is linked, not copied: every test that uses it runs the same steps.
* A test can use the same component more than once.
* Component names are unique in a project. Regular group names don't have to be.
* Removing a component from a test doesn't delete it. Deleting a component removes it from every test.
* A component has no parameters of its own. To run it with different values, set [variables](/editing-tests/variables.md) before it.
* A component can't be inserted inside another component or inside an [if block](/editing-tests/conditional-logic-if-else.md).
{% endhint %}
## Make a component
1. [Group the steps](/editing-tests/grouping-steps.md) you want to reuse. If they're in a bigger group, split it so the reusable steps have a group of their own.
2. In the test, click **Make component** on the group's header.
The group stays where it was in the test and is now listed under **Components** in the main navigation. Its name must be unique among the project's components. If another component already has that name (letter case doesn't matter), rename the group first.
{% hint style="info" %}
**Tip:** to build a new test on top of a component, use [New test from here](/creating-tests/new-test-from-here.md). Components in the copied part stay linked, regular groups are copied.
{% endhint %}
## Insert an existing component
In a test, choose to insert a component at the place where you want it, then search for the component and pick it. You can do this in an existing test or while creating a new one.
### The same component more than once
A test can contain the same component several times, for example to log in as two different users. Every occurrence runs the same steps, and a change made in one of them shows up in all of them, in this test and in every other test.
### Run a component with different values
A component has no parameters. To make it behave differently in different places, use [variables](/editing-tests/variables.md):
1. Use variables in the component's steps, for example `{{login}}` and `{{password}}`.
2. Before each occurrence of the component, add a group with **Set variable** steps that set those variables to the values you need.
Variables set earlier in a test are available in every later step, including the steps of a component. The values that apply when the component runs are the last ones set before it.
To give a variable a default value for the whole project or for a run, use a [profile](/editing-tests/variables.md) instead.
## Edit a component
Components are edited inside a test, the same way as any other group: add, change, move or delete steps. Every change applies to all tests that use the component.
{% hint style="warning" %}
Before editing, check which tests use the component (**Show related tests**). A change made for one test can break the others.
{% endhint %}
To open a component for editing from the **Components** page, open the component, click **Edit component**, and choose one of the tests that use it.
A component that isn't used in any test can't be edited, because there is no test to edit it in. Insert it into a test first.
## Change a component for one test only: unlink
**Unlink** (in the component's menu in the test) replaces the component in this one test with a regular group: a copy of its steps named ` - duplicate`. You can then change the copy without affecting other tests.
* Only this occurrence in this test is replaced. Other tests, and other occurrences of the component in this test, stay linked.
* The component itself isn't changed or deleted.
* Later changes to the component won't reach the copy.
## Split a component
Splitting a component works like [splitting a group](/editing-tests/grouping-steps.md#split-a-group): the steps after the split point move to a new group. With a component, both parts are components, and the split happens in **every** test that uses it. The new component is placed right after the original one in each of those tests.
## Remove a component from a test
**Remove from this test** removes this occurrence from the test. The component stays in the project, even if no test uses it anymore. It's still listed on the **Components** page and you can insert it again.
This is different from removing a regular group: a regular group that isn't used anywhere else is deleted together with its steps.
## Components page
**Components** in the main navigation lists all components in the project, with the number of tests that use each one.
Open a component to see its steps (read only), or use the actions menu:
| Action | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Edit component** | Opens the component in one of the tests that use it. |
| **Duplicate** | Creates a new component with the same steps, named ` - duplicate`. The copy isn't used in any test. |
| **Rename** | Changes the name in every test. The name must be unique among the project's components. |
| **Show related tests** | Lists the tests that use the component. Disabled when no test uses it. |
| **Delete** | Deletes the component and removes it from every test that uses it. This can't be undone. If tests use it, you have to confirm by typing a confirmation word. |
You can also select several components and delete them at once.
### Folders
Components can be organized in folders, the same way as [tests](/organizing-tests/organizing-tests-with-folders.md). Components have their own folder tree: a "Login" folder under Components and a "Login" folder under Tests are unrelated.
{% hint style="danger" %}
**Deleting a folder permanently deletes the components inside it**, including those in its subfolders, and removes them from every test that uses them. The confirmation shows how many components will be deleted. To keep the components, move them out of the folder first.
{% endhint %}
## Components in the API, MCP and YAML
| Task | Public API (`https://api.bugbug.io/v2/`) |
| ---------------------------------------------- | ------------------------------------------------------------------------- |
| List components | `GET /components/` (filters: `query`, `folderId`, `noFolder`) |
| Create a component not used in any test | `POST /components/` |
| Tests that use a component | `GET /components/{id}/usage/` |
| Insert a component into a test | `POST /tests/{testId}/insert-component/` with `componentId` and `atIndex` |
| Keep a copy in one test (UI: Unlink) | `POST /tests/{testId}/detach-component/` with `componentId` |
| Remove a component and its steps from one test | `POST /tests/{testId}/remove-component/` with `componentId` |
| Remove from one test (deprecated) | `POST /tests/{testId}/unlink-component/` with `groupId` |
| Delete a component from all tests | `DELETE /groups/{id}/` |
| Make a group a component | `PATCH /groups/{id}/` with `"isComponent": true` |
**Which ID to use.** In a test, each group and component has an `id` and an `originGroupId`:
* `id` identifies this occurrence in this test. Use it to unlink, move or remove that occurrence. If a test contains the same component twice, the two occurrences have different `id`s.
* `originGroupId` is the component itself. It's the same in every test.
Inserting, removing and detaching a component accept either ID. For `remove-component` and `detach-component`, use the occurrence `id` when the component appears more than once in the test; an ambiguous component ID returns 400.
**Unlink in the UI means `detach-component` in the public API:** the test keeps a copy of the steps and the component stays. The deprecated `unlink-component` endpoint instead removes the steps from the test. It keeps its old behavior for existing clients and accepts the occurrence `id` as `groupId`.
Changing a component to a regular group with `PATCH /components/{id}/` (or the equivalent `/groups/{id}/`) and `"isComponent": false` is allowed only when it has exactly one test relation; otherwise it returns 400. Two occurrences in the same test count as two relations. The same rule applies to PUT. Use `detach-component` to keep a copy in one test while leaving the reusable component available.
The same operations are available as tools in the [BugBug MCP server](/ai-testing/mcp.md). In [exported YAML](/export-import-and-backup/import-export.md), a test refers to a component with `component_source`, and the component's steps are in its own file.
## FAQ
If I change a component, do all tests that use it change?
Yes. A component is linked, not copied. Every change to its steps applies to every test that uses it, and to every occurrence in the same test. To change it for one test only, [unlink](#change-a-component-for-one-test-only-unlink) it in that test.
Can I pass parameters to a component?
Not directly. Use variables in the component's steps and set them with **Set variable** steps in a group before the component. See [Run a component with different values](#run-a-component-with-different-values).
Can I use the same component twice in one test?
Yes. Each occurrence runs the same steps. To run them with different values, set variables before each occurrence.
Can a component contain another component?
No. A component is a group, and a group contains steps, not other groups. Put the components one after another in the test instead.
Can I put a component inside an if block?
No. An if block can't contain a component. You can do the opposite: put an if block inside the component, so the whole component's steps run only when the condition is met. See [Conditional logic](/editing-tests/conditional-logic-if-else.md).
What happens when I remove the last test that uses a component?
The component stays in the project and is listed on the Components page, with no related tests. Delete it there if you don't need it.
What's the difference between Unlink, Remove from this test and Delete?
* **Unlink** replaces the component in this test with a regular copy of its steps.
* **Remove from this test** removes the component and its steps from this test only.
* **Delete** deletes the component and its steps from the project and from every test that uses it.
In the public API, use `detach-component` for UI **Unlink**, `remove-component` for **Remove from this test**, and `DELETE /groups/{id}/` for **Delete**. The deprecated `unlink-component` endpoint removes steps, so it does not match UI **Unlink**.
Why can't I name my component the same as another one?
Component names must be unique in a project, ignoring letter case. Regular groups can share names.
Can I copy some steps out of a component?
Yes. Select the steps, copy them and paste them where you need them. The pasted steps are ordinary steps and aren't linked to the component. See [Copy and paste steps](/editing-tests/grouping-steps.md#copy-and-paste-steps).
Can I merge a group into an existing component?
No. Making a group a component creates a new component from it. To use an existing component instead, insert that component and remove the group.
---
# 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/editing-tests/components.md?ask=&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.
