> 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/getting-started/complete-product-guide.md).

# Complete Product & Workflow Guide

A complete, outcome-led guide to ContextQA web, API, mobile, Salesforce, AI-assisted, execution, reporting, integration, agent, and administration workflows.

## Quick answer

ContextQA is an AI-assisted quality engineering platform for turning requirements and application context into reviewable web, API, mobile, and Salesforce tests; organizing those tests into reusable suites and plans; running them on demand or from delivery workflows; and preserving screenshots, recordings, logs, traces, and failure analysis for a release decision. Start with one non-production business journey, connect only the systems it needs, require human review for generated coverage, and expand after the resulting evidence is trustworthy.

[**Download the complete product and workflow guide (PDF)**](https://github.com/indivatools/gitbooks-docs/tree/main/docs/.gitbook/assets/contextqa-complete-product-workflow-guide.pdf)

{% hint style="info" %}
**Who is this for?** Evaluators, QA leaders, SDETs, testers, developers, product managers, administrators, and AI-agent users who need one shareable map of ContextQA capabilities and operating workflows.
{% endhint %}

## ContextQA in one workflow

```mermaid
flowchart LR
    A[Requirements and application context] --> B[Generate or author tests]
    B --> C[Human review and approval]
    C --> D[Suites, plans, data and environments]
    D --> E[Web, API, mobile and Salesforce execution]
    E --> F[Video, screenshots, logs, traces and results]
    F --> G[Failure analysis, defects and release decision]
    G --> H[Maintain, rerun and improve coverage]
    H --> B
```

The workflow is deliberately evidence-led. Generation creates a candidate test, not proof. A run creates observations, not an automatic release decision. Reviewers decide whether the scope, environment, data, assertions, and captured evidence are sufficient for the business risk.

## Product capability map

| Capability                          | What a team can do                                                                                                           | Primary business outcome                                                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Workspace onboarding                | Connect a non-production application, optional repository, team tools, teammates, and an AI client                           | Reach a usable first workflow without assembling a separate automation stack                                          |
| Requirements management             | Create or import requirements from documents, tickets, application crawls, designs, and other supported sources              | Preserve traceability from intent to generated and reviewed tests                                                     |
| Web testing                         | Author natural-language and structured browser steps, prerequisites, loops, conditions, reusable groups, and custom steps    | Automate customer journeys while keeping tests readable                                                               |
| API testing                         | Configure requests, authorization, variables, response storage, chaining, and payload assertions                             | Validate contracts and business data, not only status codes                                                           |
| Mobile testing                      | Upload approved app builds, author gestures and mobile actions, map devices, and run mobile plans                            | Exercise Android and iOS journeys with reusable evidence                                                              |
| Salesforce testing                  | Generate and execute Salesforce UI and connected API workflows                                                               | Cover metadata-heavy business processes and role-specific journeys                                                    |
| Data and environments               | Reuse environment values, global and local variables, data profiles, generated values, proxy profiles, and browser profiles  | Run the same intent safely across approved targets and data sets                                                      |
| Suites and plans                    | Group coverage, map execution targets, set recovery behavior, schedule runs, and retain plan history                         | Turn individual cases into repeatable regression and release workflows                                                |
| Execution evidence                  | Watch runs, inspect screenshots, video, network and console logs, traces, duration, and reruns                               | Produce a reviewable answer to what ran, where, and what happened                                                     |
| AI-assisted maintenance             | Use self-healing, failure insights, suggested fixes, and reviewed reruns                                                     | Reduce maintenance effort without hiding genuine product failures                                                     |
| Ship autonomous quality engineering | Coordinate code analysis, change impact, bug reproduction, application signals, root-cause evidence, and regression creation | Move from an incoming engineering signal to reviewable release evidence without adding another disconnected framework |
| Change-impact analysis              | Map eligible code changes to related tests and reviewed regression scope                                                     | Focus execution while keeping a defensible fallback when scope is uncertain                                           |
| AI Insights and crawl               | Turn observed activities or a bounded crawl goal into requirements and candidate tests                                       | Find coverage opportunities from actual application behavior                                                          |
| Integrations                        | Connect issue trackers, source providers, Slack, CI/CD preparation, webhooks, and approved infrastructure                    | Keep quality evidence in the team's delivery workflow                                                                 |
| MCP and AI agents                   | Let compatible AI clients discover authorized ContextQA tools through OAuth                                                  | Bring managed test workflows into Claude, ChatGPT, Cursor, Codex, and other approved clients                          |
| Administration and governance       | Manage people, roles, authentication, tokens, organization defaults, storage, audit records, billing, and usage              | Apply least privilege and retain operational accountability                                                           |

## 1. Set up the workspace

Use the [self-serve onboarding flow](/getting-started/self-serve-onboarding.md) to connect a reachable non-production application and a dedicated test identity. Add code, Jira, Linear, or Slack only when the evaluation needs them. The onboarding flow can also show an optional **Connect your AI agent** step with copyable MCP configuration and a credential-free agent skill; OAuth and the user's ContextQA permissions still control access.

For authenticated discovery, use a test account that does not encounter interactive CAPTCHA or multi-factor prompts during the automated session. Do not weaken those controls in production. Review the final setup summary, then verify the selected application, repository, integrations, teammates, and generated drafts from the dashboard.

## 2. Bring requirements into ContextQA

ContextQA can begin from manually written requirements or supported source material such as issue-tracker items, uploaded requirement documents, application crawls, designs, recordings, or API descriptions. The exact sources available depend on workspace configuration.

A reliable requirement-to-test workflow is:

1. State the business outcome, actor, preconditions, important data rules, and stopping condition.
2. Attach or connect the approved source.
3. Generate candidate scenarios across happy path, negative, boundary, field-validation, and end-to-end needs.
4. Review assumptions, prerequisites, variables, destructive actions, and expected results.
5. Publish only the cases that represent the intended behavior.
6. Keep the requirement relationship so coverage gaps and later changes remain explainable.

Use [requirements management](/web-testing/requirements-management.md), [AI test generation](/ai-features/ai-test-generation.md), and [crawl-generated requirements](/ai-features/crawl-requirements.md) for source-specific instructions.

## 3. Build web tests

Web tests can combine natural-language AI actions with structured navigation, verification, API, database, custom-code, document, loop, condition, and reusable step-group actions. Use a validated login test as a prerequisite when several cases share authentication; this avoids copying credentials and login steps into every case.

Prefer business intent over brittle implementation wording. For example, verify that an approved refund changes the order status and balance instead of referring to a CSS class. Use structured steps when request fields, assertions, loop boundaries, or data types must be explicit. See [creating test cases](/web-testing/creating-test-cases.md), the [test steps editor](/web-testing/test-steps-editor.md), and [step groups](/web-testing/step-groups-tutorial.md).

## 4. Build API and contract tests

An API workflow should validate the data that drives the business operation, not only whether a response returned success. Configure the request, authorization, headers, parameters, and body; store the response; then assert status, schema, field types, required values, precision, formats, and error behavior.

Use [API chaining](/api-testing/api-chaining.md) to extract identifiers or tokens from one response and reuse them in later requests. Use environments for target URLs and secret-backed values. For specification-led coverage, start with the [OpenAPI contract testing guide](/testing-with-ai-coding-agents/openapi-contract-testing.md), then preserve the specification revision and generated test review as evidence.

## 5. Build mobile tests

Upload an approved Android or iOS build, select eligible devices, and create mobile cases with actions and gestures that match the target application. Group stable cases into mobile plans and use device mappings intentionally; a single passing device does not establish cross-device compatibility.

Keep application builds, provisioning material, credentials, and test data in approved storage. Start with [mobile prerequisites](/mobile-testing/prerequisites.md), [uploading apps](/mobile-testing/uploading-apps.md), [creating mobile tests](/mobile-testing/creating-mobile-tests.md), and [mobile test plans](/mobile-testing/mobile-test-plans.md).

## 6. Test Salesforce and connected enterprise journeys

ContextQA supports Salesforce UI automation and workflows that combine Salesforce screens with API, data, and downstream application steps. Use descriptive business checkpoints—record ownership, stage transition, required fields, related-list updates, permissions, and audit evidence—rather than relying on screen navigation alone.

See [Salesforce testing](/salesforce-testing/salesforce-testing.md) and [Salesforce and enterprise workflows](/business-use-cases/salesforce-and-enterprise-workflows.md). For a journey that crosses systems, keep each handoff and its resulting identifier visible in the test so a reviewer can trace the failure boundary.

## 7. Manage data and environments

Choose the narrowest scope that fits the value:

| Data mechanism         | Best use                                                          |
| ---------------------- | ----------------------------------------------------------------- |
| Local variable         | Temporary value used by one test                                  |
| Global variable        | Approved non-secret value reused across the workspace             |
| Environment value      | Target-specific URL, account reference, or secret-backed value    |
| Test data profile      | Rows of data used to repeat the same intent with different inputs |
| Runtime response value | Identifier, token, or data extracted from an earlier API step     |
| Generated value        | Unique email, timestamp, identifier, or other fresh test input    |

Do not put passwords or tokens in requirement text, step descriptions, screenshots, or the knowledge base. Review [test data management](/web-testing/test-data-management.md), [environment data management](/web-testing/environment-data-management.md), and [data-driven testing](/web-testing/data-driven-testing-tutorial.md).

## 8. Organize and execute regression coverage

Use folders and labels to make cases discoverable, suites to group executable coverage, and plans to combine suites with browsers or devices, environments, parallelism, notifications, recovery actions, and schedules. The Test Cases filter can narrow results by module as well as lifecycle and execution criteria.

Before a plan becomes a release gate:

1. Confirm the intended suite membership and prerequisites.
2. Pin the target environment and data revision.
3. Start with low parallelism and confirm data isolation.
4. Define stopped, aborted, failed, and not-executed handling.
5. Enable the evidence needed for the risk.
6. Run once manually and review every unexpected outcome.
7. Add scheduling or CI/CD only after the baseline is stable.

See [test suites](/web-testing/managing-test-suites.md), [test plans](/web-testing/test-plans.md), [running tests](/execution/running-tests.md), and [scheduling](/execution/scheduling.md).

## 9. Review execution evidence

The run—not the test title—is the evidence record. Confirm the workspace, plan or case, trigger, environment, browser or device, start and end times, total duration, rerun count, status counts, and build reference. Then inspect the relevant step, screenshot or video frame, console and network entries, and trace.

Treat these states differently:

* **Passed** means the configured assertions passed for that run and environment.
* **Failed** means at least one required outcome was not satisfied.
* **Aborted** or **Stopped** means execution ended before a complete verdict.
* **Not executed** or **Queued** is not evidence that the behavior passed.
* **Unknown** is the correct conclusion when a terminal result or required artifact cannot be retrieved.

Use [test results](/reporting/test-results.md), [execution history](/reporting/execution-history.md), and [video and screenshots](/execution/video-and-screenshots.md).

## 10. Diagnose, repair, and report failures

Start with the first meaningful failed assertion and the evidence captured by the original run. ContextQA can provide Failure Insights, a proposed category, reasoning, and—when available—a suggested fix. Overlay or pop-up blockers should be distinguished from genuine application behavior defects. Keep AI conclusions as hypotheses until the evidence and a controlled rerun support them.

Self-healing can recover from routine locator drift during execution. Suggested fixes are reviewed changes after a failure. Neither should turn a real product problem into a passing result without evidence. When a genuine defect is confirmed, create or update the connected tracker record with the minimum necessary evidence and remove sensitive values before submission.

See [failure analysis](/reporting/failure-analysis.md), [AI self-healing](/web-testing/self-healing.md), and [flaky test detection](/reporting/flaky-test-detection.md).

## 11. Use Ship for autonomous quality workflows

[Ship](/ship/ship.md) connects the places quality work begins with the evidence engineers and release owners need. Its customer-facing workflows include:

* **Code analysis:** understand an approved repository and use that context to propose coverage.
* **Pull-request impact:** map a change to affected flows and reviewed regression scope.
* **Bug analysis and reproduction:** pick up a report from a connected issue or collaboration tool, reproduce it, capture evidence, and investigate the likely cause.
* **Production-signal coverage:** identify eligible application anomalies, reproduce them in a controlled environment, and turn confirmed behavior into regression coverage.
* **Root cause and suggested repair:** preserve the original failure, provide an evidence-backed hypothesis, and hand reviewed context to an engineer or approved AI coding agent.
* **Continuous release quality:** run targeted, post-merge, scheduled, or broader fallback coverage and retain the release decision trail.

Ship can initiate and coordinate these workflows, but it does not silently merge code, approve generated tests, apply a suggested fix, or make a release decision. Workspace permissions and delivery policy determine which actions can run automatically and which require human approval.

## 12. Use change impact, crawl, and AI Insights

[PR Impact Analysis](/ai-features/pr-impact-analysis.md) maps an eligible pull or merge request to related tests, supporting evidence, confidence, and a reviewed regression scope. Review the source change, scope boundary, target environment, selected cases, and fallback before running impacted coverage. A zero-test or partial analysis is not a passing release signal.

[AI Insights](/ai-features/ai-insights.md) analyzes eligible captured sessions to identify user activities and potential coverage gaps. A selected activity can become a crawl-backed requirement and generated cases. Use the observation as a source, then review the assumptions and scenarios before publishing.

For a fresh application crawl, set an explicit goal, credentials, allowed routes, and stopping condition. Review which roles, states, and routes were reachable before using generated requirements or tests as shared coverage. See [crawl-generated requirements](/ai-features/crawl-requirements.md).

## 13. Connect delivery tools and AI agents

Use [Integrations & Plugins](/integrations/integrations.md) for connected issue trackers, source providers, notifications, and infrastructure. A connection can show **Reconnect needed** when provider access has been removed or expired. Reconnect or intentionally disconnect and connect the desired account; do not paste OAuth responses or tokens into documentation or test steps.

Use the [ContextQA MCP server](/mcp-server/overview.md) when an approved AI client should discover and call authorized test-management, execution, result, and analysis tools. The safe operating sequence is **discover → read → propose → approve → mutate → verify**. Start with read-only verification and use narrowly scoped credentials and workspace permissions.

## 14. Administer and govern the platform

Administrators manage users, roles, authentication, API tokens, organization defaults, storage, audit records, and billing. Use least privilege, separate human and automation identities, prefer expiring scoped tokens, and keep secrets in an approved secret manager. Review the system audit trail after changes to access or organization-wide defaults.

Use [administration](/administration/administration.md), [roles and permissions](/administration/roles-and-permissions.md), [API tokens](/administration/api-tokens.md), [system configuration](/administration/system-configuration.md), and [billing and usage](/administration/billing-and-usage.md).

## Common end-to-end workflows

| Goal                                         | Recommended flow                                                                                                                  | Evidence to retain                                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Validate a user story                        | Jira or Linear item → candidate tests → reviewer approval → suite and plan → run → linked result                                  | Requirement relationship, approved cases, run, screenshots or video, defect link if needed |
| Validate an API contract                     | OpenAPI description → generated and manual negative cases → chained execution → schema and payload assertions                     | Specification revision, requests and masked responses, assertions, run result              |
| Validate a pull request                      | Connected source provider → impact report → reviewed test scope → target deployment → impacted run → broader fallback when needed | Change reference, analysis boundary, selected cases, environment, run result               |
| Reproduce a reported bug                     | Ticket or Slack context → bounded reproduction → generated scenario → evidence and root cause → reviewed defect or fix            | Original report, steps, environment, recording, logs, result, reviewer decision            |
| Convert an application anomaly into coverage | Eligible session → anomaly review → controlled reproduction → candidate regression test → reviewer approval → suite assignment    | Session reference, observed pattern, reproduction evidence, approved case, future run      |
| Analyze a codebase for coverage              | Approved repository → bounded code analysis → application and flow map → candidate tests → reviewer approval                      | Repository and branch, analysis identity, scope, limitations, accepted cases               |
| Run a regression gate                        | Stable suite → plan configuration → manual baseline → CI/CD or schedule → result check → release decision                         | Plan revision, trigger, build, environment, duration, status counts, evidence links        |
| Drive testing from an AI agent               | OAuth MCP connection → read-only discovery → proposed operation → human approval → execution → result retrieval                   | Agent request, selected tool, workspace, run ID, terminal result, evidence                 |

## Adoption checklist

* Choose one business-critical but reversible non-production journey.
* Define its release decision and required evidence before building tests.
* Use one shared login prerequisite and controlled test data.
* Review generated steps, negative paths, data effects, and assertions.
* Establish a stable manual baseline before adding schedules or CI.
* Connect only the delivery tools needed for the pilot.
* Define who can generate, approve, execute, repair, and publish tests.
* Measure valid coverage, false failures, time to diagnose, maintenance effort, and usable release verdicts.
* Expand by module only after the first workflow is repeatable.

## Related documentation

* [Browse documentation by role](/documentation-by-role/by-role.md)
* [Business use cases](/business-use-cases/business-use-cases.md)
* [Evaluation and governance](/evaluation-and-governance/evaluation.md)
* [Migration to ContextQA](/migrate-to-contextqa/migration.md)
* [Use the documentation with search and AI](/reference/using-contextqa-docs-with-ai.md)

{% hint style="info" %}
**Want to map ContextQA to one of your real workflows?** [**Book a Demo →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=complete_product_guide) — Bring one requirement, application journey, or release gate and review the generated coverage and evidence.
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/getting-started/complete-product-guide.md?ask=<question>&goal=<user_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.