# Knowledge Base

{% hint style="info" %}
**Who is this for?** All roles — especially QA engineers who want to teach ContextQA's AI how to handle application-specific UI patterns, consent banners, popups, and test conventions.
{% endhint %}

A Knowledge Base is a set of plain-English instructions stored at the workspace level that the ContextQA AI agent reads before and during every test execution. It is the mechanism for encoding persistent, application-specific knowledge into the test engine — so you write the instruction once and every test in the workspace benefits automatically.

***

## Why You Need a Knowledge Base

The ContextQA AI agent is trained to test general web and mobile applications. But every production application has quirks: a GDPR consent modal that appears on first load, a live chat widget that opens over content, a feature tour that appears on every login, a staging-only banner that covers part of the UI.

Without guidance, the AI agent either attempts to interact with these overlays (causing false failures) or gets confused by them. With a knowledge base entry like *"If a cookie consent modal appears, click 'Accept All Cookies' before any other interaction"*, the AI handles it correctly on every run.

***

## Accessing the Knowledge Base

1. Open your ContextQA workspace.
2. In the left navigation, go to **Knowledge Base** (route: `/td/:versionId/Knowledge_Base`).
3. The Knowledge Base list shows all entries for this workspace.

> **Access note:** Knowledge Base requires a plan that includes AI features. If the Knowledge Base menu item is grayed out or missing, contact your workspace administrator.

***

## Creating a Knowledge Base Entry

1. From the Knowledge Base list, click **+ New Knowledge Base**.
2. Enter a **Title** — a short label describing what this entry handles (e.g., "Cookie consent banner", "Chat widget dismissal", "Payment test card").
3. Enter the **Prompt** — the plain-English instruction the AI will follow. See the [Writing Effective Prompts](#writing-effective-prompts) section below.
4. Click **Save**.

The entry is immediately active for all test executions in this workspace.

***

## Writing Effective Prompts

The AI interprets prompts as instructions to follow whenever the described condition is encountered. Write prompts as imperative sentences.

### ✅ Good prompt patterns

| Situation                          | Prompt                                                                                                                                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cookie consent modal               | `If a cookie consent banner, GDPR notice, or privacy consent dialog is visible, click the button labelled "Accept All Cookies" or "Accept" immediately before any other action.`              |
| Live chat widget                   | `If a live chat widget, help bubble, or Intercom button opens in the bottom corner of the screen, close it by clicking the X or minimize button before interacting with other page elements.` |
| Feature tour / product walkthrough | `If a product tour, onboarding guide, or "Get started" wizard appears as an overlay or modal, click "Skip", "Dismiss", or "Close" to exit it before proceeding.`                              |
| Test payment card                  | `On any payment form, always use the test credit card number 4111 1111 1111 1111, expiry date 12/29, and CVV 123. These are test credentials that bypass real payment processing.`            |
| Two-factor authentication          | `If a two-factor authentication prompt appears, enter the code 123456. This code is accepted in the staging environment.`                                                                     |
| Loading indicators                 | `If a loading spinner, skeleton screen, or "Please wait" overlay is present, wait for it to disappear before interacting with the page.`                                                      |

### ❌ Avoid these patterns

| Anti-pattern                      | Why it fails                                                             |
| --------------------------------- | ------------------------------------------------------------------------ |
| `Handle cookie popups`            | Too vague — the AI doesn't know what "handle" means                      |
| `The app sometimes shows a popup` | Not an instruction; no action specified                                  |
| `Be careful on the payment page`  | Ambiguous — no concrete behavior described                               |
| `Click X to close the chat`       | Too specific — the selector may change; describe the widget type instead |

### Prompt length and scope

* Keep each knowledge base entry focused on **one specific situation**.
* For complex applications, create multiple entries (one per pattern) rather than one long combined entry.
* The AI reads all entries before each run, so there's no performance cost to having many entries.

***

## Scoping Knowledge Bases to Specific Runs

When a knowledge base is workspace-scoped, it applies to every test execution. To apply a knowledge base only to specific runs:

1. When executing a test case, click the **Settings** icon next to Run.
2. Under **Knowledge Base**, select the specific entry to apply.
3. Click Run.

Via the MCP server:

```python
execute_test_case(
    test_case_id=18688,
    knowledge_id="kb_abc123"   # ID from list_knowledge_bases()
)
```

Use `list_knowledge_bases()` to retrieve the ID for a specific entry.

***

## Managing Knowledge Base Entries

| Action                   | How                                                              |
| ------------------------ | ---------------------------------------------------------------- |
| Edit an entry            | Click the entry name → Edit                                      |
| Delete an entry          | Click the three-dot menu → Delete                                |
| Disable without deleting | Not directly supported — delete and recreate when needed         |
| Duplicate                | Not directly supported — create a new entry with similar content |

***

## MCP Tools for Knowledge Bases

| Tool                                  | Use                                              |
| ------------------------------------- | ------------------------------------------------ |
| `list_knowledge_bases`                | Get all knowledge bases and their IDs            |
| `create_knowledge_base`               | Create a new knowledge base programmatically     |
| `execute_test_case(knowledge_id=...)` | Attach a knowledge base to a single test run     |
| `execute_test_plan(knowledge_id=...)` | Attach a knowledge base to a full plan execution |

### Create via MCP

```json
{
  "title": "Cookie consent banner",
  "prompt": "If a cookie consent banner, GDPR notice, or privacy consent dialog is visible, click the button labelled Accept All Cookies or Accept immediately before any other action."
}
```

***

## Common Use Cases

### E-commerce applications

```
If a promotional popup or discount offer modal appears, close it by clicking the X button or "No thanks" link before interacting with the main content.
```

### SaaS applications with onboarding

```
If a feature announcement modal, "What's new" dialog, or onboarding checklist panel is visible when you arrive on a page, click Dismiss, Close, or X to close it before proceeding with the test.
```

### Multi-tenant applications

```
When the application asks to select a tenant or organization, always select "Test Organization" from the dropdown.
```

### Staging environments

```
If a staging environment banner or "Test mode" notice appears at the top of the screen, ignore it and proceed with the test. Do not click on it.
```

***

## Related Pages

* [Custom Agents](https://learning.contextqa.com/ai-features/custom-agents)
* [AI Test Generation](https://learning.contextqa.com/ai-features/ai-test-generation)
* [Running Tests](https://learning.contextqa.com/execution/running-tests)
* [MCP: list\_knowledge\_bases](https://learning.contextqa.com/mcp-server/tool-reference/telemetry-and-agents)

{% hint style="info" %}
**70% less human effort with AI test generation and self-healing.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See AI generate, execute, and maintain tests for your application.
{% endhint %}