# Tutorial: Step Groups

{% hint style="info" %}
**Who is this for?** Testers and SDETs who want to eliminate duplicate steps across test cases. You will build one reusable step group and share it across multiple tests.
{% endhint %}

Step groups let you save a sequence of test steps as a reusable unit — like a function in code. Instead of copying the same login steps into 20 test cases, you create one `SG_Login` step group and insert it wherever authentication is needed. When the login flow changes, you update the step group once and every test case that uses it picks up the change automatically.

In this tutorial you will:

1. Create a step group from existing test steps
2. Insert the step group into a second test case
3. Pass variables to the step group for different credentials
4. Update the step group and verify the change propagates

**End result:** A reusable login step group shared across two test cases, parameterized with variables so each test can pass its own credentials.

## Prerequisites

* A ContextQA account with at least one workspace ([sign up](https://accounts.contextqa.com/onboard))
* A web application with a login page you can test against
* At least one existing test case that includes login steps (see [Quickstart guide](https://learning.contextqa.com/getting-started/quickstart) or [Creating test cases](https://learning.contextqa.com/web-testing/creating-test-cases))
* Familiarity with [core concepts](https://learning.contextqa.com/getting-started/core-concepts) — specifically test cases, steps, and variables

***

## Step 1: Identify the steps to extract

Open an existing test case that includes a login sequence. A typical login flow has three to five steps:

```
Step 1: Navigate to ${ENV.BASE_URL}/login
Step 2: Type admin@example.com in the Email field
Step 3: Type SecurePass123! in the Password field
Step 4: Click the Sign In button
Step 5: Verify the dashboard page loads
```

These steps appear in many test cases — any test that requires an authenticated user starts with this same sequence. Extracting them into a step group eliminates the duplication.

***

## Step 2: Create a step group from the selected steps

1. In the test case details screen, select the checkbox next to each login step (steps 1–5 in the example above).
2. A floating toolbar appears at the bottom of the screen. Click **Group**.
3. The **Create Step Group** dialog opens. Enter a name for the step group: `SG_Login`.

> **Important:** Prefix step group names with `SG_` by convention. This makes them easy to find when searching and immediately identifies them as reusable components in the step list.

4. Click **Create**.

ContextQA creates the step group and replaces the selected steps in your test case with a single **Step Group** step that references `SG_Login`. The original steps now live inside the step group.

**Verify it worked:** The test case step list now shows a single step labeled `SG_Login` where the five login steps used to be. Click **Show Step Group Steps** on the step to expand and see the individual steps inside.

***

## Step 3: Add variable placeholders to the step group

Hard-coded credentials limit the step group to one user account. Replace the fixed values with `${variable}` placeholders so each test case can pass its own credentials.

1. In the left sidebar, navigate to **Test Development**.
2. Click the **Step Groups** tab to see all step groups in the workspace.
3. Click `SG_Login` to open it.

{% hint style="warning" %}
**Any edits made to the step group will reflect in all test cases that use this step group.** This is the power of step groups — and the reason to be intentional about changes.
{% endhint %}

4. Find the step that types the email address. Click the step to edit it and replace the hard-coded email with a variable placeholder:

```
Type ${sg_username} in the Email field
```

5. Find the step that types the password. Replace the hard-coded password:

```
Type ${sg_password} in the Password field
```

6. Save the step group.

The step group now expects two runtime variables: `${sg_username}` and `${sg_password}`. When you insert this step group into a test case, ContextQA prompts you to provide values for these variables.

> **Tip:** Prefix step group variable names with `sg_` to distinguish them from test case local variables and environment parameters. This avoids accidental name collisions.

***

## Step 4: Insert the step group into a second test case

1. Open a different test case that also requires authentication — for example, a test that verifies the settings page.
2. Click **Add Step** at the position where the login sequence should run (typically the first step).
3. In the step builder, select the **Step Group** category from the left sidebar.
4. Search for `SG_Login` in the step group list. Only step groups in **Ready** or **In Review** status appear here — if your step group is missing, check its status in Test Development → Step Groups.
5. Select it. ContextQA displays the runtime variables the step group expects: `sg_username` and `sg_password`.
6. Enter the values for this test case:

| Variable      | Value                        |
| ------------- | ---------------------------- |
| `sg_username` | `settings-admin@example.com` |
| `sg_password` | `SettingsPass456!`           |

7. Click **Create Step** to add the step group to the test case.

The test case now shows `SG_Login` as its first step. At execution time, the step group expands into the individual login steps with the credentials you provided.

***

## Step 5: Run both test cases and verify

Run each test case to confirm the step group works correctly with different credentials.

1. Open the first test case (the one you extracted the step group from). Click **Run**.
2. In the execution results, expand the `SG_Login` step. Each individual step within the group has its own pass/fail status and screenshot — the step group is transparent in the report.
3. Open the second test case. Click **Run**.
4. Verify that the login steps used the different credentials (`settings-admin@example.com`) and the test passed.

**What to check in the results:**

| What to verify                              | Where to look                                                 |
| ------------------------------------------- | ------------------------------------------------------------- |
| Step group expanded into individual steps   | Step-by-step breakdown in the execution report                |
| Correct credentials were used per test case | Screenshots of the email and password fields during execution |
| Each step has its own pass/fail status      | Status indicators next to each expanded step                  |

***

## Step 6: Update the step group and see changes propagate

Suppose the login page adds a "Remember me" checkbox that you want to select during login. Update the step group once and both test cases inherit the change.

1. Navigate to **Test Development → Step Groups**.
2. Open `SG_Login`.
3. Click **Add Step** after the "Click the Sign In button" step.
4. Add a new step before the sign-in click:

```
Select the Remember me checkbox
```

5. Reorder the step so it appears before the "Click the Sign In button" step.
6. Save the step group.

Now re-run both test cases. Both executions include the new "Remember me" step without any changes to the test cases themselves.

***

## Summary

You built a reusable step group in six steps:

1. **Identified** repeated login steps across test cases
2. **Created** a step group (`SG_Login`) from selected steps using the **Group** action
3. **Parameterized** the step group with `${sg_username}` and `${sg_password}` variables
4. **Inserted** the step group into a second test case with different credential values
5. **Verified** both test cases run correctly with their own credentials
6. **Updated** the step group once and confirmed the change propagated to both test cases

One step group now serves as the single source of truth for the login sequence across your workspace.

## Next steps

* **Create step groups for common patterns:** Navigation sequences (`SG_Navigate_To_Settings`), form completion (`SG_Fill_Contact_Form`), teardown actions (`SG_Logout`), and dismissing persistent UI elements (`SG_Dismiss_Cookie_Banner`).
* **Combine with data-driven testing:** Use step group variables alongside test data profile variables to run the same step group with dozens of credential sets. See [Tutorial: Data-driven testing](https://learning.contextqa.com/web-testing/data-driven-testing-tutorial).
* **Clone an existing test case as a step group:** If you already have a standalone test case that you want to reuse as setup in other tests, use the three-dot menu → **Clone → As Step Group** instead of rebuilding it. See [Managing test suites](https://learning.contextqa.com/managing-test-suites#cloning-a-test-case-as-a-step-group).
* **Track step group dependencies:** Open any step group and click the **Test Cases** tab to see every test case that references it. Use this view before making breaking changes.

## Related pages

* [Test steps editor](https://learning.contextqa.com/web-testing/test-steps-editor) — reference for all step types including step group configuration
* [Core concepts](https://learning.contextqa.com/getting-started/core-concepts#step-groups) — step groups in the platform hierarchy
* [Managing test suites](https://learning.contextqa.com/managing-test-suites#cloning-a-test-case-as-a-step-group) — converting test cases to step groups
* [Tutorial: Data-driven testing](https://learning.contextqa.com/web-testing/data-driven-testing-tutorial) — parameterizing tests with data profiles
* [Creating test cases](https://learning.contextqa.com/web-testing/creating-test-cases) — test case creation methods

{% hint style="info" %}
**Reuse once, update everywhere — no code required.** [**Start Free Trial →**](https://app.contextqa.com/register) — Or [**Book a Demo →**](https://contextqa.com/book-a-demo/) to see step groups with your application.
{% endhint %}