> 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/ai-features/ai-insights.md).
# AI Insights
{% hint style="info" %}
**Who is this for?** QA engineers, SDETs, and QA managers who want to base their test suite on how customers actually use the application, and to find gaps between real user behavior and existing test coverage.
{% endhint %}
AI Insights analyzes real user sessions captured on a domain you choose, groups them into the distinct **activities** users perform, and reports what those activities reveal — console errors encountered along the way, how many activities you have already turned into tests, and which ones still need coverage. From any discovered activity, you can generate a test case, so your suite tracks real usage instead of assumptions.
## Quick answer
ContextQA AI Insights turns observed application usage into prioritized testing opportunities. It analyzes captured sessions, reconstructs distinct user activities, surfaces console errors and uncovered journeys, and lets a tester generate a requirement and test case from an activity. Scheduled runs help teams compare real usage with automated coverage over time.
## What this page covers
Each analysis is called an **AI Insight**, and it runs on a schedule you set. Every time it runs, it produces a **run** — a point-in-time snapshot of the activities found in that window. You can switch between runs, watch a run progress phase by phase, and compare how coverage changes over time.
Unlike [AI Test Generation](/ai-features/ai-test-generation.md), which creates tests from a source you provide (a ticket, a URL, a design), AI Insights works backward from observed behavior: it looks at what users did, then tells you what is worth testing.
***
## Key concepts
| Term | What it means |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AI Insight** (session) | A single analysis configured against one domain, an optional session window, and a schedule. The **New Session** action creates one. |
| **Run** | One execution of an insight. Each run analyzes the sessions in its window and produces a report. Insights that run on a schedule accumulate many runs over time. |
| **Activity** | A distinct path a user took through your application, reconstructed from one or more sessions. In the report, an activity is also shown as a **journey**. Each has a priority, a narrative, and any console errors captured during it. |
| **Coverage** | How many activities you have converted into test cases, out of the total discovered. |
| **Console error** | A JavaScript or network error captured in the browser console during a session. AI Insights treats these as real, user-visible defects. |
| **Requirement** | The record a generated test case is created from. Activities you generate tests for produce a **crawl requirement** — see [Generate requirements from a crawl](/ai-features/crawl-requirements.md). |
***
## Opening AI Insights
1. Open your ContextQA workspace.
2. In the left navigation, go to **AI Insights** (route: `/td/:versionId/ai-insights`).
3. The page opens on two tabs:
* **Overview** — workspace-level metrics across every insight and run.
* **Sessions & Activities** — the list of insights you have configured.
The header carries a **New Session** action that creates a new insight from either tab.
### Overview tab
The **Overview** tab (`/td/:versionId/ai-insights/overview`) summarizes AI Insights activity for the whole workspace version. Use the date range picker at the top (which defaults to **All time**) to change the window.
A **Key metrics** row shows six tiles:
| Tile | What it shows |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Sessions captured** | How many user sessions were captured. |
| **Activities captured** | How many distinct activities were reconstructed from those sessions. |
| **Requirements generated** | AI-generated requirements attributed to an AI Insights activity. Manual and Jira uploads are not counted. |
| **Test cases created** | How many test cases were generated from those requirements. |
| **Mean time to requirement** | The mean latency from an activity being surfaced to its requirement being generated, in hours. |
| **Converted to suite** | The percentage of generated test cases that sit in a suite. |
The first four tiles show a **last-run delta** — a `+` count with an upward-trend icon — when the most recent run of each insight added something new.
Below the metrics, a **Trend** chart plots **Activities** against **Test cases** over the selected period. Switch the granularity between **Day**, **Week**, and **Month**.
If no data has been captured yet, the tab shows "No AI Insights data yet."
### Sessions & Activities tab
The **Sessions & Activities** tab (`/td/:versionId/ai-insights/sessions`) lists every insight configured for this workspace version. Search the list with the **Search AI Insights** box, and filter by date range, created date, status, or domain.
Each row shows:
| Column | What it shows |
| ----------------- | -------------------------------------------------------- |
| **ID** | The insight identifier. |
| **Name / Domain** | The insight name and the domain it analyzes. |
| **Activities** | How many activities the latest run found. |
| **Test cases** | How many test cases have been generated from it. |
| **Coverage** | How many activities have been converted into test cases. |
| **Status** | Where the insight is in its run (see below). |
| **Range** | The session window the run analyzed. |
| **Created At** | When the insight was created. |
The status column reflects where each insight is:
| Status | Meaning |
| --------------- | ------------------------------------------------------------------------- |
| **Scheduled** | The insight is waiting for its next scheduled run. |
| **In Progress** | A run is analyzing sessions. The status shows a percentage while it runs. |
| **Ready** | Activities are ready to review. Open the insight to view its report. |
| **Completed** | The run finished. |
| **Stopped** | The run was stopped before completion. |
| **Failed** | The run couldn't complete. Use **Re-Run** to start it again. |
Each row has an action menu with **Edit** and **Re-Run**. Click a row to open its report.
{% hint style="info" %}
**Prerequisite:** AI Insights needs captured session data for the domain you select. The **Domain Name** dropdown lists only domains that have recorded sessions, with the number of events available for each. If your domain does not appear, no session data has been captured for it yet.
{% endhint %}
***
## Creating an AI Insight
1. From either tab, click **New Session**.
2. Select the **Domain Name** — the site whose sessions you want to analyze. Each option shows the captured event count, for example `app.example.com (12,345 events)`.
3. Enter a **Name** — a descriptive label for this insight.
4. Choose a **Scheduler** value to control how often the analysis runs:
* **Once** — runs a single time (default).
* **Daily** — runs once every day.
* **Weekly** — runs once every week.
* **Biweekly** — runs once every two weeks.
5. Set the **Date** and **Time** for the first (or only) run. Both default to five minutes from now, and the scheduled time must be in the future.
6. To refine the analysis, expand **Advanced Options**:
* **URL Path** — narrow the analysis to a section of the domain, for example `/checkout`. This field searches the paths captured under the selected domain as you type, so pick a domain first.
* **Date Range** — limit analysis to sessions recorded between a start and end date.
* **Additional Context** — optional guidance for the AI, for example "focus on booking flows."
7. Click **Submit**.
ContextQA queues the insight and begins processing at the scheduled time.
{% hint style="info" %}
The **Date Range** in Advanced Options controls which sessions are analyzed. The **Date** and **Time** at the top of the form control when the analysis runs.
{% endhint %}
### Editing the schedule
Open an insight and use the **Edit** action to change its scope, context, or schedule. When you edit an existing insight, the schedule shows as a read-only summary until you click **Change schedule**; new insights open with the schedule editor already expanded.
* **Pause and resume** — a scheduled insight can be paused so no further runs fire. Activities already generated are kept, and you can still start a run by hand. Saving a schedule change to a paused insight resumes it.
* **In-progress lock** — while a run is in progress, its schedule can't be edited.
***
## Working with runs
Open an insight to see its report. Because a scheduled insight runs repeatedly, the report always shows one **run** at a time — by default, the latest.
### Run summary and run switcher
The header identifies the insight and the run you are viewing:
* The **title** shows the environment the insight ran against, with a link to the domain.
* A **run summary** describes the selected run, for example `Latest run · Today, Jul 7 · 12 journeys`.
* The **run switcher** (labeled **Switch run**) lists every run, newest first, with its date and outcome. Select a run to view it; the choice is pinned to the page URL so you can share a link to a specific run.
* **Re-Run** starts a fresh run immediately.
* **Context** opens the additional context you set, and a schedule button shows the cadence and whether the schedule is active or paused.
A run can end in several states, shown in the switcher and on the report:
| Run outcome | Meaning |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| Journeys count (for example, **12 journeys**) | The run finished and produced activities. |
| **Analyzing…** | The run is still processing. It shows the current phase and a progress percentage. |
| **Queued** | The run is waiting to start. |
| **Superseded** | A newer run replaced this one. |
| **No journey** / **No activities** | The run finished but found nothing to report. |
| **Partial** / **Incomplete** | The run finished only some of its work. Use **Re-Run** to try again. |
| **Unreachable** | The site could not be reached. |
| **Rate limited** | The run was throttled. |
### Run-phase timeline
While a run analyzes sessions, it moves through five phases in order:
1. **Selecting sessions**
2. **Processing video**
3. **Identifying user activities**
4. **Generating journeys**
5. **Matching existing tests**
The report shows the active phase, a progress bar, and a stage checklist. Use **Refresh** to update a run that is still analyzing, or **Re-Run** to restart a run that stopped early.
***
## Reading the report
When a run is ready, the report opens in a two-pane layout with an overview strip above it.
### Overview strip
A collapsible **Overview** section summarizes the run in four cards:
| Card | What it shows |
| --------------------- | --------------------------------------------------------------- |
| **Activities found** | The total number of distinct activities discovered in this run. |
| **Console errors** | The number of console errors captured across all activities. |
| **P1 critical flows** | How many activities are high priority. |
| **Already processed** | How many activities have already produced tests. |
### Activity list
The left pane lists every activity. Each row shows:
* A **priority badge** (`P0` for the highest priority, then `P1`, `P2`, and lower).
* A **console error** badge (or **0 errors** when there are none).
* A **steps** count.
* When the activity was **captured**.
Search the list with the box at the top, and select the checkbox on one or more rows to generate tests in bulk. When rows are selected, an action bar appears with **Generate test cases (N)** and **Clear**.
### Activity details
Select an activity to open its detail panel. The header shows the priority, the title, and one primary action:
* **Open Requirement** — opens the requirement linked to this activity, when one exists.
* **Generate Test Case** — generates a test for this activity when it has no linked requirement.
The panel has three sub-tabs:
* **Insight** — explains the activity. It includes a **Why this matters** callout with the AI's reasoning, a **User journey** narrative describing the steps the user took, and a collapsible **Discarded activities** list of steps the AI analyzed but left out of this activity.
* **Console Errors** — lists the console errors captured during the session.
* **Replay** — plays an embedded session replay, when a recording is available.
***
## Generating test cases from activities
When an activity has no test coverage, turn it into one or more test cases directly from the report. ContextQA generates each test case by crawling your live application, so every generation produces a **crawl requirement**.
1. Select one or more uncovered activities using their row checkboxes, or open a single activity and click **Generate Test Case**.
2. In the action bar, click **Generate test cases (N)**. The **Generate test cases** drawer opens.
3. The drawer analyzes the selected activities first (the **Analysis** step), then walks you through **Clarifications**, **Inputs**, and **Crawl**.
{% hint style="info" %}
If every activity you selected has already produced a requirement, the drawer shows an **Already generated** state with a link to each existing requirement. Pick at least one activity that hasn't been generated yet.
{% endhint %}
For the full walkthrough of the drawer — answering clarifications, configuring inputs, and reading the crawl requirement it produces — see [Generate requirements from a crawl](/ai-features/crawl-requirements.md).
***
## Summary
AI Insights closes the loop between how users behave and what your tests cover:
1. **Create** a session against a domain, an optional session window, and a schedule.
2. **Review** each run's activities, their priorities, and their console errors.
3. **Track** how many activities you have already converted into tests, run over run.
4. **Generate** test cases for the activities that matter most.
Because you can schedule an insight to run daily, weekly, or biweekly, your test suite keeps pace with how customers actually use your application.
***
## Related pages
* [Generate requirements from a crawl](/ai-features/crawl-requirements.md) — the crawl workflow that turns activities into test cases, and how to read a crawl requirement
* [AI Test Generation](/ai-features/ai-test-generation.md) — generate test cases from tickets, URLs, designs, and other sources
* [Requirements Coverage Gaps](/ai-features/requirements-coverage-gaps.md) — find requirements that lack test coverage
* [AI Assistant](/ai-features/ai-assistant.md) — the in-app AI assistant for navigation and test creation
* [Test Results](/reporting/test-results.md) — understanding execution result pages
## Frequently asked questions
What is ContextQA AI Insights?
AI Insights is the user-behavior analysis area in ContextQA. It analyzes captured sessions for a configured domain, groups behavior into activities or journeys, reports associated console errors and coverage, and provides a path to generate tests for uncovered activity.
How is AI Insights different from AI Test Generation?
AI Test Generation starts from a source you deliberately provide, such as requirements, a ticket, URL, design, or API definition. AI Insights starts from observed user sessions and identifies the activities that users actually performed before recommending coverage.
Does AI Insights automatically turn every activity into a test?
No. Review the activity, its priority, narrative, errors, and existing coverage first. You choose an uncovered activity and start test generation, including any required clarification and input review.
What does AI Insights coverage measure?
Coverage compares activities discovered by the insight with activities that have been converted into generated requirements and tests. It is activity coverage within AI Insights, not a universal guarantee of complete product or requirements coverage.
Why would a run show partial, unreachable, or rate-limited?
Those states mean the run could not complete its normal analysis window. Review the status and phase, verify that the configured site is reachable and eligible for capture, and use **Re-Run** after correcting the condition.
## See AI Insights on a real application
Choose a customer journey whose real usage is difficult to translate into regression coverage. In a guided demo, the ContextQA team can show how captured activity becomes an insight, a coverage decision, and a reviewable test.
[**Book a Demo →**](https://contextqa.com/book-a-demo/)
---
# 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/ai-features/ai-insights.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.