> 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/business-use-cases/complex-web-and-authentication.md).

# Complex Web and Authentication

## Quick answer

Automate multi-system web journeys involving MFA, email, browser extensions, file handling, APIs, and databases. Use this page to connect the business problem to a supported ContextQA workflow, its expected value, and its operating considerations.

## What this page covers

{% hint style="info" %}
**Business problem:** A critical user journey rarely stays on one page. It may cross a web application, identity provider, inbox, browser extension, file exchange, API, and database before the business outcome is complete.
{% endhint %}

Model the journey as one business transaction, but keep setup concerns reusable. ContextQA test cases can combine natural-language UI steps with prerequisites, variables, API calls, database checks, and evidence from the same run.

![ContextQA Test Cases library showing a portfolio of enterprise workflow tests and their latest status](/files/dLKh2Jl24PuKefhH2mKq)

## Pattern: separate reusable setup from business verification

1. Create a prerequisite for the common authenticated session.
2. Store usernames, passwords, tokens, mailbox identifiers, and environment URLs as parameters or secrets.
3. Capture runtime values—record IDs, confirmation numbers, or links—as variables.
4. Keep the main test focused on the customer or employee outcome.
5. End with assertions that prove both the visible UI result and, where required, the downstream system state.

This pattern prevents every scenario from duplicating login logic and makes authentication changes easier to maintain.

## MFA and one-time-code flows

Use an environment-approved mechanism for retrieving a test-only code:

* **TOTP/authenticator:** generate a current code from a protected test secret.
* **Email OTP or magic link:** retrieve the message through an approved mailbox or mail-testing API, parse the code or link, and continue the browser flow.
* **Identity provider redirect:** allow the prerequisite to complete the redirect and hand the authenticated session to the main case.

Never log the seed, password, access token, or full message body. Mask sensitive values in reports, and use non-production identities with controlled access and reset procedures.

## Testing a customer browser extension

Testing an application-under-test extension is different from using the ContextQA recorder extension. For a customer extension:

1. Provide the approved extension build and manifest for the test environment.
2. Configure a compatible managed browser session with the extension installed.
3. Launch the web application and extension in the same session.
4. Exercise the cross-surface workflow—for example, capture data on a website, open the extension panel, submit it, and verify the result in the web application.
5. Record console and network evidence from the relevant surfaces.

Extension installation, browser policies, incognito behavior, permissions, and update strategy vary by deployment. Validate them during the proof of concept before promising broad browser coverage.

## File and document flows

ContextQA web tests can cover file selection, drag-and-drop upload, download initiation, and visible processing results. Combine UI steps with assertions such as:

* correct file name, type, size, and processing status;
* expected validation message for an unsupported or damaged file;
* downloaded file exists and has the expected metadata or content;
* API or database record references the uploaded artifact;
* no sensitive file content appears in logs or shared screenshots.

Use synthetic files that exercise size, encoding, language, corruption, and boundary conditions without exposing customer data.

## UI, API, and database in one business flow

A mixed-channel test is useful when the outcome cannot be proved from the UI alone. A payment example can:

1. Create a cart through an API.
2. Complete checkout through the web UI.
3. Capture the order identifier.
4. Query an approved read-only database connection or verification API.
5. Verify the order state and displayed confirmation agree.

Keep database access read-only whenever possible, isolate test data, and put cleanup in a controlled prerequisite or teardown process.

## Self-healing and visual checks

Self-healing helps a test locate an intended control after non-breaking DOM or layout changes. It does not change the business assertion. Review healed steps after significant releases so the team can confirm the test still interacts with the intended element.

Add visual, accessibility, responsive-layout, or content assertions when the experience itself is part of the requirement. Treat a visual difference as evidence to review, not automatically as a product defect.

## Success measures

* Critical journeys automated end to end, including authentication and connected systems
* Authentication setup reused across cases
* Secrets exposed in steps or reports (target: none)
* Failures with enough evidence to assign an owner without rerunning
* Maintenance edits caused by login, DOM, or dependency changes

## Related documentation

* [Step groups and reusable prerequisites](/web-testing/step-groups-tutorial.md)
* [Environment data management](/web-testing/environment-data-management.md)
* [Database steps](/web-testing/database-steps.md)
* [API chaining](/api-testing/api-chaining.md)
* [Execution evidence](/execution/video-and-screenshots.md)


---

# 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/business-use-cases/complex-web-and-authentication.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.