> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/web-testing/creating-test-cases.md).

# Creating Test Cases

{% hint style="info" %}
**Who is this for?** QA engineers, testers, and developers who want to create web test cases using any of the four creation methods available in ContextQA.
{% endhint %}

## Overview

ContextQA provides a unified three-step creation dialog with four methods: **AI Assistance**, **Import Files**, **Record & Play**, and **Create manually**. Use this page when you need to create a test case and verify it in the test case editor.

{% hint style="warning" %}
**Recorder versus extension testing:** **Record & Play** uses the ContextQA recorder capability to capture a web flow. Testing a browser extension that belongs to the application under test is a separate environment setup: the extension build must be installed in a compatible managed browser, and its permissions and cross-surface workflow must be validated. See [Complex web and authentication workflows](/business-use-cases/complex-web-and-authentication.md).
{% endhint %}

***

## Opening the creation panel

{% stepper %}
{% step %}

### Navigate to test development

Open <https://app.contextqa.com> and sign in to your workspace. Select **Test Cases** from the left sidebar to open the test cases list.
{% endstep %}

{% step %}

### Select New Test Case

Select **New Test Case** in the page header. The **Create Test Case** dialog opens at step 1.
{% endstep %}

{% step %}

### Select a creation method

The panel presents a method selection screen with up to four options (availability depends on your plan and feature flags):

| Method            | Description                                                               | Button Label                 |
| ----------------- | ------------------------------------------------------------------------- | ---------------------------- |
| **AI Assistance** | Provide a description and let ContextQA generate test cases automatically | **Start with AI Assistance** |
| **Import Files**  | Upload requirements or test files to generate test cases                  | **Import Files**             |
| **Record & Play** | Record your actions in the browser while ContextQA captures each step     | **Start Recording**          |
| **Manual**        | Define the case and its steps yourself                                    | **Create manually**          |

After selecting a method, the dialog shows step 2 with the available starting action. Select **Back** to return to the preceding step.

{% hint style="info" %}
The **Import Files** option requires the relevant upload feature to be enabled on your plan. The **Record & Play** option requires the recorder capability.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Creation methods in detail

{% tabs %}
{% tab title="AI Assistance" %}

### AI-assisted test generation

Describe your test scenario in plain English. ContextQA's AI generates all steps, locators, and assertions automatically.

**Fields:**

| Field                      | Required | Description                                                                                                                               |
| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Prerequisites**          | No       | Select existing test cases to run before this test. Available on paid plans.                                                              |
| **URL**                    | Yes      | The starting URL for the test (must begin with `http://` or `https://`). Hidden when prerequisites are selected or when targeting mobile. |
| **Description**            | Yes      | A plain-English description of the test scenario.                                                                                         |
| **Select Target Platform** | Yes      | Choose **Web Application** or **Mobile**. Mobile is available when mobile execution is enabled on your plan.                              |

**Example description:**

```
Log in with the fictional documentation account, navigate to the
Products page, search for "wireless headphones", and verify that
at least one product appears in the search results.
```

**Advanced settings (optional):**

Expand the **Advanced Settings** section to configure AI behavior:

| Setting                 | Options                                                   | Default              |
| ----------------------- | --------------------------------------------------------- | -------------------- |
| **Enable AI Smartness** | Organization Default, Expert, Fast, Strict                | Organization Default |
| **AI Action**           | Organization Default, Create Steps, Dynamic Steps, Action | Organization Default |
| **Knowledge Base**      | Select a knowledge base to provide application context    | None                 |
| **Environments**        | Select a target environment                               | None                 |

Click **Generate & Execute Test Case** to create and run the test case. If the **Generate From Crawl** feature is enabled on your plan, you can click **Generate From Crawl** to create test cases by crawling the target URL.

The AI agent parses your description into discrete steps, generates locators for each element, handles dynamic content and waits automatically, and captures screenshots and video during execution.

**Best for:** Complex multi-page flows, form submissions, checkout workflows
{% endtab %}

{% tab title="Import Files" %}

### Import test cases or requirements

Upload files to generate test cases automatically. Three modes are available:

**Mode selection:**

| Mode                    | Description                                                                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Import Test Cases**   | Upload an Excel spreadsheet (`.xlsx`, `.xls`) containing test case definitions                                                            |
| **Import Requirements** | Upload requirements documents (XLSX, CSV, TXT, PDF) or video files (MP4, MOV, WEBM, MPEG, MKV) to generate test cases from specifications |
| **Import from Jira**    | Browse and select Jira tickets to generate test cases from ticket descriptions and acceptance criteria                                    |

{% hint style="info" %}
The **Import from Jira** mode is available when a Jira integration is configured in **Settings → Plugins → Bug Reporting → Jira**. See [Jira Integration](/integrations/jira.md) for setup instructions.
{% endhint %}

**Select Target Platform:**

| Platform            | Availability                               |
| ------------------- | ------------------------------------------ |
| **Web Application** | Always available                           |
| **Mobile**          | Always available                           |
| **API**             | Available in Import Requirements mode only |

**Publish mode:**

Select how imported test cases are published:

| Mode                  | Description                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Auto Publish**      | Generated test cases are saved and published immediately                                                   |
| **Required Approval** | Generated test cases are saved in a pending state and require manual review and approval before publishing |

**Test case types:**

Select which types of test cases the AI generates. Toggle individual types on or off, or click **All Types** to include every type:

| Type                 | Description                                         |
| -------------------- | --------------------------------------------------- |
| **Positive**         | Validates expected behavior with valid inputs       |
| **Functional**       | Verifies feature functionality against requirements |
| **Negative**         | Tests error handling with invalid inputs            |
| **Edge**             | Covers boundary and unusual scenarios               |
| **Field Validation** | Checks input field constraints and formatting       |
| **End to End**       | Validates complete user workflows                   |
| **Boundary Value**   | Tests at the limits of acceptable input ranges      |

**Optional configuration:**

| Option                | Description                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| **Create Test Suite** | Automatically create a test suite containing the imported test cases. Enter a suite name.                |
| **Create Test Plan**  | Create a test plan for the imported cases. Enter a plan name. Automatically enables test suite creation. |
| **Execute Test Plan** | Run the test plan immediately after import. Available when Create Test Plan is enabled.                  |

**Context fields (optional):**

Before uploading files, you can provide additional context to improve AI test generation:

| Field                      | Description                                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| **Name**                   | A descriptive name for the requirement (e.g., "Login flow requirements")                           |
| **Additional information** | Goals, notes, or context about the requirements that help the AI generate more accurate test cases |

**File upload — Import Test Cases mode:**

Upload `.xlsx` or `.xls` files. A **Download Sample Format** link is available to get the expected spreadsheet structure.

**File upload — Import Requirements mode:**

You can upload up to **10 files** per upload. Accepted file types depend on the target platform:

Accepted file types depend on the target platform:

* **Web / Mobile:** documents (`.xlsx`, `.xls`, `.docx`, `.csv`, `.txt`, `.pdf`), image files (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`), or video files (`.mp4`, `.mov`, `.webm`, `.mpeg`, `.mkv`)
* **API:** `.json` files

{% hint style="info" %}
Attach UI mockups, screenshots, wireframes, or screen-flow documents along with your requirements. Visual context helps the AI generate more relevant and complete test cases.
{% endhint %}

When uploading requirements, the import follows a guided multi-step flow:

1. **Inputs** — Upload your files, add context, and configure platform, publish mode, and optional settings
2. **Analysis** — ContextQA analyzes the uploaded documents and extracts testable requirements
3. **Clarifications** — The AI may ask follow-up questions about ambiguous requirements. Answer them to improve test case accuracy.
4. **Generate** — Test cases are generated from the analyzed requirements
5. **Review** — Review the generated test cases before saving

{% hint style="info" %}
The Import Test Cases mode uses a shorter flow: **Inputs** → **Generate** → **Review**.
{% endhint %}

**Import from Jira mode:**

When you select **Import from Jira**, the flow adds a Jira ticket picker step:

1. **Inputs** — Configure platform, publish mode, context fields, and optional settings, then click **Continue to Jira Tickets**
2. **Pick Jira Tickets** — Search for tickets by key (e.g., `PROJ-123`) or text, browse results with infinite scroll, and select one or more tickets. Enable **Include linked tickets** to automatically pull in sub-tasks and epic children (up to 50 linked tickets). Click **Continue to Review** when your selection is complete.
3. **Analysis** — ContextQA reads the selected ticket descriptions, acceptance criteria, and linked content to extract testable requirements
4. **Clarifications** — Answer any AI follow-up questions
5. **Generate** — Test cases are generated from the Jira ticket content
6. **Review** — Review the generated test cases before saving

**Figma integration:**

When the Figma feature is enabled, select **Figma** as the source instead of file upload. Enter a Figma file URL (matching the pattern `https://www.figma.com/file/...`, `https://www.figma.com/proto/...`, or `https://www.figma.com/design/...`).

Click **Create Test Cases** to start the generation process.

{% hint style="info" %}
When importing requirements, the AI may ask clarification questions before generating test cases. After generation, you can review AI analysis, coverage gaps, and metadata from the **Requirements Details** page. See [Requirements Management](/web-testing/requirements-management.md) for the full workflow.
{% endhint %}

**Best for:** Migrating existing test libraries, generating tests from requirements documents, importing from Jira tickets, creating tests from design files

[Watch the Excel test-case import walkthrough](https://drive.google.com/file/d/1sP-9thppLX1NcEb5tI5471jaICkfMoqI/preview) or the [requirements-to-tests walkthrough](https://drive.google.com/file/d/1JtdXOKBYGoQiGa4woSapLiVOge0vrlyS/preview).
{% endtab %}

{% tab title="Record & Play" %}

### Browser recording

Record your actions in the browser while ContextQA captures each interaction as a test step.

{% hint style="warning" %}
This method requires the **ContextQA Recorder** Chrome extension. If the extension is not detected, the panel displays installation instructions with a link to the Chrome Web Store.
{% endhint %}

**When the extension is installed:**

| Field             | Required | Description                                                                  |
| ----------------- | -------- | ---------------------------------------------------------------------------- |
| **Prerequisites** | No       | Select existing test cases to run before this test                           |
| **URL**           | Yes      | The starting URL for recording. Shows your open browser tabs as suggestions. |

Click **Create Test Case** to start recording. ContextQA opens the target URL with the recorder active. Navigate and interact with your application normally — the recorder captures each click, text entry, and navigation as a step. Click **Stop Recording** to finalize.

**When the extension is not installed:**

1. Click the link to install the **ContextQA Recorder** from the Chrome Web Store
2. Enable the extension in incognito mode
3. Close and reopen the creation panel

**Best for:** UI exploration, click-heavy workflows, onboarding flows

[Watch the Record & Play walkthrough](https://drive.google.com/file/d/13Gab4J-oTb7XZVNxAZJNpDvXme-nE-iX/preview).
{% endtab %}

{% tab title="Manual Creation" %}

### Manual test case creation

Create a case directly in the dialog, then define its steps in the full builder.

1. Select **Create manually** at step 1.
2. Select **Open step builder** at step 2.
3. At step 3, enter the required **Name**.
4. Optionally set **Priority**, **Type**, **Status**, **Prerequisites**, **Labels**, advanced options, and **Description**.
5. Select **Create Test Case**.
6. Confirm the editor opens and the **Test Case created successfully** notification appears.

**Form fields:**

| Field                | Required | Description                                                            |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| **Name**             | Yes      | Descriptive test case name                                             |
| **Priority**         | No       | Select from available priority levels                                  |
| **Type**             | No       | Select the test case type                                              |
| **Status**           | No       | Draft, Ready, In Review, Approved, Obsolete, or Rework. Default: Ready |
| **Prerequisites**    | No       | Select existing test cases to run before this test                     |
| **Labels**           | No       | Add labels for organization and filtering                              |
| **Testcase Timeout** | No       | Maximum execution time in minutes (1–40). Default: 20                  |
| **Description**      | No       | Rich text description of the test case                                 |

**Test data options:**

| Field                   | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| **Test Data Profile**   | Select a data profile for parameterized testing                            |
| **Data Driven**         | Enable to run the test across multiple data sets from the selected profile |
| **Data Set**            | When not data-driven, select a specific data set from the profile          |
| **Iteration From / To** | When data-driven, define the range of data set iterations                  |

**Additional toggles:**

| Toggle                        | Description                                         |
| ----------------------------- | --------------------------------------------------- |
| **Mobile Testing**            | Switch the test case type from web to mobile        |
| **Extension Used**            | Mark whether the ContextQA Chrome extension is used |
| **Avoid auto wait for steps** | Disable automatic wait insertion between steps      |

Select **Show Advanced Options** to review additional execution settings when needed. Select **Create Test Case** to save the case and open its details page.

**Best for:** Precise control over test metadata, data-driven testing configuration, complex assertions
{% endtab %}
{% endtabs %}

## Verify a manually created test case

After creation, confirm that the details page shows the new name and the **Test Steps**, **Relationships**, and **Version History** tabs. The side panel should show **Test Case**, **Variables**, **Used in Test**, and **Run History**. Return to **Test Cases** and search by the new title or assigned `TC-` identifier to verify list placement.

### Verify the test from the list

1. Return to **Test Cases**.
2. Enter the test's `TC-` identifier or a distinctive part of its title in **Search by ID or Title**.
3. Confirm that the row shows the expected **Type**, **Priority**, **Result**, **Status**, and **Labels**.
4. Switch between **List** and **Modular** view when you need a different way to browse the collection.
5. Use **Filter** to narrow a large test library instead of relying on naming alone.

{% hint style="success" %}
A successful creation is not complete verification. Run the saved test once and review its steps, console, network activity, screenshot, video, and trace before promoting it into a shared suite.
{% endhint %}

### Run a documentation-safe verification

When the test exists only to produce product documentation evidence, keep it separate from valuable regression tests:

1. Prefix the title with `DOC-` and include the feature and expected outcome—for example, `DOC — Test Cases — Open list and verify controls`.
2. Use fictional data and a non-production environment.
3. Reuse a stable login prerequisite instead of copying credentials into steps.
4. Add a viewport-safe verification that names only controls visible together on the page.
5. Run the test and wait for a final passed or failed status.
6. Open **View Run Results** and review all evidence before using it in documentation.
7. Record the test ID and run ID in the documentation task.
8. Delete the disposable test from the active list after the evidence is approved. Do not edit or delete the source regression test when you created the documentation test by duplication.

For every capability on the live execution and completed result screens, see [Execution and test results](/reporting/test-results.md).

***

## Mobile platform selection

When you select **Mobile** as the target platform (from the AI Assistance or Import Files tabs), a mobile device setup screen appears before starting execution.

**Concurrency indicators** appear in the header showing parallel execution slots and queue status.

| Field                    | Required | Description                                                                                            |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| **Select Platform**      | Yes      | Choose **iOS** (IPA) or **Android** (APK)                                                              |
| **Select Device**        | Yes      | Pick a device from the available device pool (options load based on selected platform)                 |
| **App Build**            | Yes      | Select the app build to test. If no builds are found, click **Go to Upload Page** to upload one first. |
| **Desired Capabilities** | No       | Review and edit key-value capability pairs. Some fields (like `app_url` and `os_type`) are read-only.  |

Click **Start Execution** to launch the mobile test. If maximum concurrency is reached, ContextQA queues the test and you can click **Skip and continue** to close the dialog while the test waits in the queue.

For more details on mobile test setup, see the [Mobile Testing](/mobile-testing/mobile-testing.md) section.

***

## Verifying generated test cases

After AI generates test cases (from the AI Assistance or Import Files methods), a verification screen displays the results.

Each generated test case shows:

* **Title** with an internal ID badge (e.g., `TC-1`)
* **Description** of the test scenario
* **Steps** with detailed actions
* **Expected Result** for the test case
* **Source badges** indicating where the test case was derived from

**Actions available:**

* Click **Save** on an individual test case to save it to your project
* Click **Save All Test Cases** to save all generated test cases at once
* Click **Cancel** to discard the generated test cases

If any test cases were skipped during generation, a **Skipped Test Cases** section appears with the reason each case was skipped.

***

## Frequently asked questions

<details>

<summary>How long does it take to create a test case?</summary>

Creation time varies with workflow complexity, the selected authoring method, and the application under test. Review every generated or recorded step before publishing the test case.

</details>

<details>

<summary>Can I import existing test cases from spreadsheets?</summary>

Yes. Select **Import Files** in the creation dialog, choose **Import Test Cases** mode, and upload an `.xlsx` or `.xls` file. Download the sample format to see the expected column structure. ContextQA maps your spreadsheet columns to test case fields automatically.

</details>

<details>

<summary>What browsers and devices are supported?</summary>

ContextQA supports all major browsers for test execution:

* **Chrome** (desktop + headless)
* **Firefox**
* **Safari** (macOS)
* **Edge**
* **Mobile Chrome / Safari** (via device emulation)

For real-device mobile testing, see the [Mobile Testing](/mobile-testing/mobile-testing.md) section.

</details>

<details>

<summary>Are screenshots and videos stored automatically?</summary>

ContextQA can attach screenshots, video, and trace evidence to a run result when recording is enabled and the execution type supports those artifacts. Open the completed result and check the **Screenshots**, **Video**, and **Trace** tabs before relying on the evidence. Availability and retention can depend on workspace configuration, permissions, and policy.

</details>

<details>

<summary>Can I run the same test case across multiple environments?</summary>

Yes. ContextQA supports environment-based test execution. You can define multiple environments (Development, Staging, Production) and run any test case against any environment by selecting it at execution time. Environment-specific variables (base URLs, credentials, API keys) are managed separately so your test cases remain portable.

</details>

<details>

<summary>How does self-healing work if my application changes?</summary>

ContextQA's AI Configuration (self-healing) continuously monitors element locators. When an element changes — for example, a button moves or an ID changes — the AI automatically finds the updated element using visual context, text content, and semantic analysis. The system flags failed locators for review and heals them with one click. See [Self-Healing Tests](/web-testing/self-healing.md) for configuration details.

</details>

<details>

<summary>What are the AI Smartness modes?</summary>

AI Smartness controls how the AI generates test steps:

* **Expert** — The AI takes more time to analyze the application and produces thorough, detailed steps
* **Fast** — The AI prioritizes speed and generates steps quickly with less analysis
* **Strict** — The AI follows your description exactly with minimal interpretation
* **Organization Default** — Uses the AI Smartness setting configured by your organization administrator

</details>

<details>

<summary>What is the difference between Auto Publish and Required Approval?</summary>

When importing test cases via the **Import Files** method, you can choose a publish mode:

* **Auto Publish** saves and publishes generated test cases immediately — they are ready to run right away.
* **Required Approval** saves generated test cases in a pending state. A team member must review and approve each test case before it becomes available for execution. This is useful for teams that require peer review of test content.

</details>

***

## Best practices

{% hint style="success" %}
**Name tests descriptively** — Use the format `[Page] - [Action] - [Expected Result]` (e.g., `Login Page - Valid Credentials - Dashboard Loads`). This makes test results immediately understandable.
{% endhint %}

{% hint style="info" %}
**Start with happy-path tests** — Create and validate your positive test cases first, then add negative scenarios (invalid inputs, error states) once the base flow is verified.
{% endhint %}

{% hint style="warning" %}
**Avoid hard-coded waits** — Don't use `Wait 5 seconds` steps. Instead, use `Wait for element` or `Wait for network idle` actions. ContextQA's AI handles timing automatically.
{% endhint %}

***

## Related documentation

* [Requirements Management](/web-testing/requirements-management.md) — Upload requirements, review AI analysis, and track coverage gaps
* [Debugging Test Cases](/web-testing/debugging-test-cases.md) — Step through execution with breakpoints and live variables
* [Test Steps Editor](/web-testing/test-steps-editor.md) — Detailed guide to all available step actions
* [Version History](/web-testing/version-history.md) — Track, compare, and restore previous test case versions
* [Managing Test Suites](/web-testing/managing-test-suites.md) — Organize test cases into suites for batch execution
* [Self-Healing Tests](/web-testing/self-healing.md) — AI-powered test maintenance
* [Test Data Management](/web-testing/test-data-management.md) — Variables, CSV imports, and data-driven testing
* [AI Test Generation](/ai-features/ai-test-generation.md) — All 10 AI test generation methods
* [Mobile Testing](/mobile-testing/mobile-testing.md) — Mobile test creation and execution
* [Execution & Reporting](/execution/execution.md) — Run tests, view results, set up CI/CD
* [Execution and Test Results](/reporting/test-results.md) — Monitor a live run and inspect steps, logs, screenshots, video, and trace evidence

***

{% hint style="info" %}
**Ready to create your first test?**

[Open ContextQA Platform](https://app.contextqa.com) · [View Test Steps Reference](/web-testing/test-steps-editor.md) · [Book a Demo](https://contextqa.com/book-a-demo/)
{% endhint %}


---

# 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://learning.contextqa.com/web-testing/creating-test-cases.md?ask=<question>&goal=<endgoal>
```

`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.