> 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/test-plans.md). # Test Plans {% hint style="info" %} **Who is this for?** Testers, SDETs, and QA managers who want to organize test suites into structured execution plans with scheduling, parallel execution, and CI/CD integration. {% endhint %} A test plan is the top-level execution unit in ContextQA. It groups one or more test suites, assigns browser or device configurations, and defines execution settings such as parallelism, timeouts, and recovery behavior. Once a plan is created, you can run it on demand, schedule it to run automatically, or trigger it from a CI/CD pipeline. ## Prerequisites * You have at least one test suite with test cases in the workspace. * You are on the **Test Development** page (click the pencil/test icon in the left sidebar). * You are on the **Test Plans** tab within Test Development. *** ## Browsing test plans The **Test Plan** page lists every plan in the current workspace version. Two tabs sit at the top: * **Test Plans** — the list of plans (shows a live count). * **Schedules** — all schedules across plans (shows a live count). The toolbar above the list provides: * A search box with the placeholder **Search by ID, Title, or Label…**. * A **Filter** button. You can filter by **Tags**, **Last Run** result, **Created Date**, **Updated Date**, and **Last Run Date**. Active filters appear as removable chips below the toolbar. * A column-settings button to show or hide columns, and an auto-refresh button. * A **New Test Plan** button to start the plan creation wizard. Each row shows the plan **Name**, its **Last Run** status, and an actions cell with **Run**, **Stop**, and **Edit** controls. Click a plan name to open its detail page. *** ## Creating a test plan ContextQA uses a three-step wizard to create a test plan. ### Step 1: Plan details 1. Navigate to **Test Development → Test Plans**. 2. Click the **New Test Plan** button. 3. Fill in the plan details: * **Test Plan Name** — a descriptive name (4–250 characters). * **Labels (Optional)** — tag chips for categorization. Type a label and press Enter to add it. * **Description (Optional)** — free-text description of the plan's purpose and scope. * **Hide on Dashboard** — toggle this on if you don't want the plan to appear on the main dashboard. * **Send Notification** — toggle this on to send notifications when the plan runs. When enabled, each run sends a notification by email and to your connected Slack channel. An email field appears for recipients — enter each email address and press Enter to add it. 4. Click **Next** to proceed. ### Step 2: Test machines and suites selection 1. The wizard shows a two-panel layout: * **Available Test Suites** — all suites in the workspace, searchable by name and filterable by label. * **Selected Test Suites** — suites you have added to this plan. 2. Select one or more suites in the **Available Test Suites** panel and click the right arrow (**Add Selected**) to move them to the **Selected Test Suites** panel. 3. To remove a suite, select it in the **Selected Test Suites** panel and click the left arrow (**Remove Selected**). 4. Drag suites in the right panel to set the execution order. 5. Click **Next** to proceed. ### Step 3: Plan settings 1. Set **Parallel Execution** — the number of parallel browser nodes (1–100). Higher values run suites concurrently for faster completion. 2. Select **Capture Screenshots** — choose **None**, **All Steps**, or **Failed Steps** (default). 3. Expand **Additional Settings** to configure: * **Page Load Timeout** — seconds to wait for a page to load (default: 30). * **Element Timeout** — seconds to wait for an element to appear (default: 30). * **Environment** — select an environment record to control which base URLs and variables the plan uses. * **Knowledge Base** — select a knowledge base to provide the AI agent with application-specific context during execution. * **Test Data Profile** — select a data profile for parameterized test data. 4. Expand **Recovery Actions** to configure failure behavior: | Setting | Options | Default | | --------------------------------------- | ---------------------------------------------------------------- | ---------------------------------- | | **On Major Test Step Failure** | Abort and run next test case, Report and continue next test step | Abort and run next test case | | **On Test Step Pre-Requisite Failure** | Abort and run next test case, Report and continue next test step | Abort and run next test case | | **On Test Case Pre-Requisite Failure** | Abort test plan, Report and continue next test case | Abort test plan | | **On Test Case Abort** | Clean up and reuse current session, Start with new session | Clean up and reuse current session | | **On Test Suite Pre-Requisite Failure** | Abort test plan, Report and continue next test suite | Abort test plan | 5. Click **Create** to save the test plan. *** ## Test plan detail page After creating a plan, click its name in the Test Plans list to open the detail page. The detail page shows a header, a stats summary, and a tabbed interface for managing every aspect of the plan. ### Header The header shows a back arrow to return to the test plan list, the plan name, a **Saved** indicator, and the workspace version label. Two actions sit on the right: | Button | Description | | -------- | ------------------------------------------------------------------------------------------ | | **Edit** | Opens the plan in the edit wizard, where you can change plan details, suites, and settings | | **Run** | Launches a new execution run for the plan | ### Stats summary Below the header, a stats bar provides a quick overview: * **Suites** — number of test suites in the plan. * **Test Cases** — total test cases across all suites. * **Schedule** — current schedule configuration. * **Latest Run** — run ID, relative timestamp, and pass/fail/blocked counts with an overall status badge. ### Tabs The detail page organizes plan management into the following tabs: | Tab | Purpose | | ------------- | --------------------------------------------------------- | | **Overview** | Plan summary, suites list, and add/view test cases | | **Runs** | Recent execution runs for the plan | | **Reports** | Full run report for the plan's latest run | | **History** | Version history of plan changes, with compare and restore | | **Schedules** | Schedule management with calendar view | | **CI/CD** | Integration cards and REST API endpoints | | **Settings** | Execution settings, notifications, and recovery actions | *** ## Overview tab The Overview tab is the default view when you open a test plan. It contains two main sections. ### Plan summary card The plan summary card shows key metadata: * **Sprint / Release** — the sprint or release associated with the plan. * **Start** and **End** — timestamps from the most recent run. Displays an em-dash if the plan hasn't been executed. * **CI/CD Trigger** — how the most recent run was triggered (manual, scheduled, or CI/CD). ### Suites in plan Below the summary, the suites list shows every suite assigned to the plan. Each row displays the suite name, suite code (for example, `S-123`), and test case count. **Viewing test cases in a suite:** 1. Click **View Test Cases** on any suite row. 2. A read-only drawer opens, listing the suite's test cases with their last result, last run date, and module. To edit cases, open the test suite directly. 3. Click any test case name to navigate to its detail page. 4. Close the drawer by clicking the close button or clicking outside the panel. **Adding test suites:** 1. Click the **+ Add Test Suite** button below the suites list. 2. The **Add suites to plan** drawer slides in from the right. 3. Find suites using either layout: * **List** — a flat, searchable list of suites. * **Modular** — a **Folders / Modules** tree on the left to browse suites by folder, with the suite list on the right. 4. Search by ID, name, or tag using the search box at the top. 5. Use the tabs to narrow the list to **All Suites**, **Not in this plan**, or **Already in this plan**. 6. Select the checkbox on each suite you want to add. Selected suites appear in a preview strip at the bottom. 7. Click **+ Add selected** to attach the suites to the plan, or **Cancel** to discard. {% hint style="info" %} Suite settings you adjust for a plan are plan-specific. The original suites stay unchanged. {% endhint %} *** ## Runs tab The Runs tab displays recent execution runs for the plan. A toolbar provides a search box, a refresh button, and a **List** / **Card** view toggle. In **List** view, each row shows the run ID, a relative timestamp (for example, "2h ago"), the run duration, and a pass-rate badge. In **Card** view, each run appears as a card with its status, trigger type, and timestamp. Click a run to open its detailed results page. *** ## Reports tab The Reports tab embeds the full run report for the plan's latest run — the same Run History, Test Case Results, and Run Details panels you see on a run's results page, without the page header. *** ## History tab The History tab tracks every change made to a test plan over time. Each time you edit a plan — renaming it, changing execution settings or recovery actions, or adding and removing test suites — ContextQA records a new version. Use this tab to see what changed, who changed it, compare any two versions, and restore an earlier version when you need to roll back a change. {% hint style="info" %} This is separate from [test case version history](/web-testing/version-history.md). The History tab on the plan detail page tracks changes to the **plan** — its settings and suite membership — not to the steps inside individual test cases. {% endhint %} The tab uses a two-panel layout: a **version list** on the left and a **detail panel** on the right. ### Version list The left panel lists every version of the plan, ordered from newest to oldest. Each entry shows: | Field | Description | | ------------------ | --------------------------------------------------------------------------------------------------------- | | **Version number** | Sequential label such as `V12`, `V11`, etc. | | **Current badge** | Marks the version that is currently active. | | **Change type** | A badge showing how the version was created: **Create**, **Update**, **Restore**, or **Import**. | | **Change summary** | A short description of what changed, such as the number of fields and suites added, removed, or modified. | | **Author** | The team member who made the change. | | **Relative time** | How long ago the version was created (for example, "2 hours ago"). | Click any version to load its details in the version details panel. The list supports infinite scroll — more versions load automatically as you scroll down. If a plan has no recorded changes yet, the tab displays an empty state: "Version history will appear here once changes are made to this test plan." ### Version details Selecting a version shows its field-level changes in the detail panel, grouped by category. Tracked changes include: * **Plan settings** — name, description, labels, environment, viewport, resolution, parallel nodes, screenshot capture, page load and element timeouts, and recovery actions. * **References** — knowledge base, persona, and test data profile. * **Test Suites Added**, **Test Suites Removed**, and **Test Suites Modified** — changes to which suites belong to the plan. Each changed field shows its previous and new value so you can see exactly what the version altered. ### Comparing two versions 1. Select a version in the list and open its details. 2. Click **Compare**. 3. Choose the **from** and **to** versions to compare. ContextQA displays the two versions side by side and summarizes the differences as a count of added, removed, modified, and unchanged items. Click the swap control to reverse the comparison direction, or close the comparison to return to the detail view. ### Restoring a version 1. Select the version you want to restore from the list. 2. Click **Restore**. 3. Review the confirmation dialog, which previews the version you are restoring to and the new version number it creates. 4. Click **Restore to V*****n*** to confirm. {% hint style="info" %} Restoring doesn't overwrite history. ContextQA applies the selected version's configuration and records it as a **new** version at the top of the list, so your current version and the full change history are preserved. A restore can itself be undone by restoring an earlier version. {% endhint %} *** ## Schedules tab The Schedules tab provides a split-view layout with a schedule list panel and a calendar panel. ### Viewing schedules * The schedule list panel shows schedule cards with the schedule name, recurrence pattern, next run date, and an activate/deactivate toggle. * The calendar displays scheduled events on their target dates. Use the navigation arrows to change months, or click **Today** to return to the current date. * Collapse or expand the schedule list panel using the toggle button in the calendar header. ### Creating a schedule 1. Click the **New Schedule** button (or the **Add Schedule** button below the schedule list). 2. Fill in the schedule form: * **Name** — a descriptive name for the schedule (required). * **Date** — the start date. * **Time** — the start time. * **Repeat** — select a recurrence pattern: | Repeat | Behavior | | ------------ | --------------------------------------------------------------------------------------------------- | | Don't Repeat | Runs once at the specified date and time | | Hourly | Repeats every hour | | Daily | Repeats every day at the specified time | | Weekly | Repeats every week on the same day (the chip shows the day, for example "Weekly on Friday") | | Monthly | Repeats every month on the same date (the chip shows the day, for example "Monthly on the 8th day") | * **Notify** — an email address to notify with each scheduled run's result. 3. Click **Save**. ### Managing schedules * **Activate/deactivate** — use the toggle on each schedule card to pause or resume a schedule without deleting it. * **Run now** — click **Run now** on a schedule card to trigger an immediate execution. * **Edit** — click the edit icon to modify the schedule name, time, or frequency. * **Delete** — click the delete icon to permanently remove the schedule. *** ## CI/CD tab The CI/CD tab shows available integration options and REST API endpoints for triggering test plans from your CI/CD pipeline. ### Default integrations The integrations section displays cards for supported CI/CD platforms: * Azure DevOps * CircleCI * Codeship * Bamboo * Jenkins * AWS * TravisCI * Generic shell For detailed configuration steps, see the [Integrations](/integrations/integrations.md) section. ### REST API Two API endpoint cards describe the programmatic options for triggering a plan: | Endpoint | Method | Description | | ------------------- | ------ | -------------------------------------------------------------- | | **Start Test Plan** | POST | Starts a test plan run and returns a run ID for status polling | | **Check Status** | GET | Returns the status, result, and suite breakdown for a run | {% hint style="info" %} Your API key is available from **Settings → API Keys** in the ContextQA portal. {% endhint %} *** ## Settings tab The Settings tab provides a two-column layout for managing plan execution configuration without re-entering the edit wizard. ### Execution settings | Setting | Description | | ------------------------- | --------------------------------------------------------------------------------------------- | | **Parallel Nodes** | Number of concurrent browser nodes (1–100). Use the stepper buttons or type a value directly. | | **Capture Screenshots** | Controls when screenshots are captured: **All Steps**, **Failed Steps Only**, or **None**. | | **Page Load Timeout (s)** | Seconds the agent waits for a page to finish loading. | | **Element Timeout (s)** | Seconds the agent waits for a target element to appear on the page. | | **Knowledge Base** | Select a knowledge base to provide the AI agent with application-specific context. | | **Test Data Profile** | Select a data profile for parameterized test data. | ### Notifications * **Hide on Dashboard** — toggle this on to exclude the plan from the main dashboard view. * **Send Notification** — toggle this on to enable notifications. When enabled, each run sends a notification by email and to your connected Slack channel. Enter the recipient address in the **Email** field, which becomes editable once **Send Notification** is on. ### Recovery actions Recovery actions control what happens when a step, test case, or suite encounters a failure. Each setting offers radio button options matching the same recovery actions configured during plan creation. After making changes, click **Save Changes**. Click **Discard** to revert unsaved changes. *** ## Tips & best practices * **Start with one parallel node, then scale up.** Verify that your suites run correctly in sequence before increasing parallelism. Some test cases may have implicit ordering dependencies that surface as flaky failures under parallel execution. * **Use recovery actions to match your testing goals.** For smoke tests, set **On Major Test Step Failure** to abort and move to the next test case — you want fast feedback, not exhaustive coverage. For regression tests, set it to report and continue so you capture all failures in a single run. * **Group related suites in a single plan.** If your suites cover the same feature area or deployment, grouping them in one plan gives you a single pass/fail status and consolidated reporting. * **Schedule nightly regression runs.** Create a plan with your full regression suites and schedule it to run daily. Review the results each morning to catch regressions introduced by the previous day's changes. * **Use environments instead of hardcoded URLs.** Attach an environment record to the plan so the same plan can target staging, QA, or production without editing test case steps. * **Leverage the CI/CD tab for pipeline integration.** Use the REST API endpoints to trigger test plans from GitHub Actions, Jenkins, or any CI/CD tool, and poll for results before proceeding with deployment. *** ## Troubleshooting **The test plan doesn't appear on the dashboard** Check that the **Hide on Dashboard** toggle is off in the Settings tab or in the plan creation wizard. **Schedule isn't triggering at the expected time** Verify that the schedule is in the **Active** state (toggle is on). Confirm that the date and time are correct — scheduled times must be in the future. If you created a schedule with a past date, edit it and set a future start time. **The Run button doesn't start a new run** The plan's last run may still be executing. Wait for the current execution to complete, or stop it from the Test Plans list before starting a new run. **A suite I added isn't showing test cases** The suite may be empty. Navigate to **Test Development → Test Suites**, open the suite, and verify it contains test cases. Suites without test cases still appear in the plan but contribute zero test cases to the total count. *** ## Related pages * [Managing Test Suites](/web-testing/managing-test-suites.md) * [Running Tests](/execution/running-tests.md) * [Scheduling](/execution/scheduling.md) * [Parallel Execution](/execution/parallel-execution.md) * [Environments](/execution/environments.md) * [Mobile Test Plans](/mobile-testing/mobile-test-plans.md) * [Integrations Overview](/integrations/integrations.md) {% hint style="info" %} **70% less manual test maintenance with AI self-healing.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA create and run test plans for your web application. {% 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/test-plans.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.