# 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](/ai-features/custom-agents.md)
* [AI Test Generation](/ai-features/ai-test-generation.md)
* [Running Tests](/execution/running-tests.md)
* [MCP: list\_knowledge\_bases](/mcp-server/tool-reference/telemetry-and-agents.md)

{% 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 %}


---

# Agent Instructions: 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:

```
GET https://learning.contextqa.com/ai-features/knowledge-base.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.