> 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/knowledge-base-tutorial.md).

# Tutorial: Configure a Knowledge Base

{% hint style="info" %}
**Who is this for?** Testers, SDETs, and QA managers who want to reduce false test failures caused by cookie banners, chat widgets, onboarding tours, and other application-specific UI patterns.
{% endhint %}

Every web application has patterns that trip up automated testing — a GDPR consent banner that covers the page on first load, a live chat widget that floats over buttons, a product tour that hijacks clicks. Without guidance, the ContextQA AI agent either interacts with these overlays by mistake or gets blocked by them, causing false failures.

In this tutorial, you create two Knowledge Base entries that teach the AI to handle these patterns automatically. By the end, every test in your workspace benefits from these instructions without any changes to individual test cases.

**What you will accomplish:**

1. Create a Knowledge Base entry for handling cookie consent banners
2. Create a second entry for dismissing live chat widgets
3. Set one entry as the workspace default
4. Run a test case with the knowledge base attached and verify the AI follows your instructions

**Time:** 10 minutes

***

## Prerequisites

* A ContextQA account with a plan that includes AI features (the **Knowledge Base** menu item is visible in your left sidebar)
* At least one existing test case in your workspace — if you have not created one yet, complete the [Quickstart Guide](/getting-started/quickstart.md) first
* A test case that targets an application with a cookie consent banner or chat widget (to see the knowledge base in action)

***

## Step 1: Navigate to the knowledge base

1. Sign in to ContextQA and open your workspace.
2. In the left sidebar, click **Knowledge Base** (under the Test Plan & Results section).

The Knowledge Base list page opens. If this is your first time here, the page displays an empty state with the message "No data available."

{% hint style="info" %}
If **Knowledge Base** is grayed out or missing from the sidebar, your current plan does not include AI features. Contact your workspace administrator to upgrade.
{% endhint %}

***

## Step 2: Create your first entry — cookie consent banner

This entry teaches the AI to dismiss cookie consent banners before interacting with the page.

1. Click the **+ Add** button in the top-right corner of the page.
2. The **Create Knowledge Base** dialog opens with two required fields.
3. In the **Name** field, enter:

   ```
   Cookie consent banner
   ```
4. In the **Description** field, enter:

   ```
   If a cookie consent banner, GDPR notice, or privacy consent dialog
   is visible on the page, click the button labelled "Accept All Cookies"
   or "Accept" immediately before any other interaction. If no accept
   button is visible, click "Close" or the X button to dismiss the banner.
   ```
5. Click **Save**.

A success notification confirms "Prompt was successfully created." The entry now appears in the Knowledge Base list.

**Verification:** The list shows one row with the name "Cookie consent banner" in the **Name** column.

***

## Step 3: Create a second entry — live chat widget

Repeat the process to handle live chat widgets that float over page content.

1. Click the **+ Add** button again.
2. In the **Name** field, enter:

   ```
   Live chat widget dismissal
   ```
3. In the **Description** field, enter:

   ```
   If a live chat widget, help bubble, or Intercom-style messenger button
   opens or expands in the bottom corner of the screen, close it by clicking
   the X or minimize button before interacting with other page elements.
   Do not type into the chat input field.
   ```
4. Click **Save**.

**Verification:** The list now shows two entries. Both have a toggle in the **Status** column, but neither is marked as the default yet.

***

## Step 4: Set a default entry

The default Knowledge Base entry applies automatically to test executions. Only one entry can be the default at a time.

1. In the Knowledge Base list, find the **Cookie consent banner** row.
2. Click the toggle switch in that row.

A success notification confirms "Prompt was successfully set as default." The **Status** column now displays a **Default Prompt** badge next to the cookie consent entry.

**Verification:** The "Cookie consent banner" row shows a blue **Default Prompt** badge. The "Live chat widget dismissal" row has no badge — it is available for manual selection but does not apply automatically.

{% hint style="info" %}
To remove the default, click the toggle again. The tooltip changes from **Deactivate** (when on) to **Set as Default** (when off).
{% endhint %}

***

## Step 5: Run a test with your knowledge base

Now verify that the AI follows your instructions during execution. You can attach a knowledge base entry in two ways: through the default (which already applies) or by selecting a specific entry at execution time.

### Option A: Run with the default (automatic)

Since you set "Cookie consent banner" as the default in step 4, it applies to every execution in this workspace automatically.

1. Navigate to **Test Development** in the left sidebar.
2. Select an existing test case that targets an application with a cookie banner.
3. Click the **Run** button to execute the test.

The AI reads the default Knowledge Base entry before the run begins and follows the instruction when it encounters a cookie consent banner.

### Option B: Select a specific entry at execution time

To use a different entry (for example, the chat widget entry) for a single run:

1. In the test case details view, click the **Settings** icon next to the **Run** button.
2. In the execution settings, find the **Knowledge Base** dropdown.
3. Select **Live chat widget dismissal** from the list.
4. Click **Run**.

This overrides the default for this specific execution only. Future runs still use the workspace default.

***

## Step 6: Verify the AI followed your instructions

After the execution completes:

1. Open the execution results (click **View Report** or navigate to the result from the **Results** list).
2. Review the step-by-step screenshots. Look for the moment where the cookie banner or chat widget appeared.
3. Confirm the AI dismissed the overlay before continuing with the test steps.

**Signs it worked:**

* The cookie consent banner appears in an early screenshot and is gone in the next one — the AI clicks "Accept" without being told to in the test steps
* The test did not fail on a step that an overlay blocked
* No step interacted with the chat widget or cookie banner by mistake

**Signs it did not work:**

* A step failed because the AI clicked the banner instead of the intended element — refine the prompt wording to be more specific about which button to click
* The banner is still visible in later screenshots — the AI did not detect it; try adding alternative button labels to the description (for example, "I agree", "Got it", "OK")

***

## Summary

You created two Knowledge Base entries that teach the ContextQA AI to handle common UI obstacles:

| Entry                      | What it handles                      | Scope                                   |
| -------------------------- | ------------------------------------ | --------------------------------------- |
| Cookie consent banner      | GDPR and cookie consent dialogs      | Workspace default (applies to all runs) |
| Live chat widget dismissal | Chat widgets that float over content | Manual selection (apply per-run)        |

These entries persist at the workspace level — every team member and every test benefits from them without modifying individual test cases.

***

## Next steps

* **Add more entries** for other patterns in your application — onboarding tours, promotional popups, staging banners, MFA codes for test environments
* **Use the knowledge base with AI test generation** — when creating a test case with AI assistance, expand **Advanced Settings** and select a Knowledge Base entry to give the AI context during generation
* **Attach a knowledge base to a test plan** — in test plan settings, select a Knowledge Base entry under the **Knowledge Base** dropdown so every execution in the plan uses it automatically
* **Manage entries programmatically** — use the MCP tools `list_knowledge_bases` and `create_knowledge_base` to manage entries from AI agents or CI scripts

***

## Writing effective knowledge base entries

As you add more entries, follow these guidelines:

| Do                                                                       | Avoid                                                              |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Write imperative instructions: "Click the Accept button"                 | Vague descriptions: "Handle the popup"                             |
| Describe the visual pattern: "a banner at the top of the page"           | Over-specific selectors: "Click the element with id='consent-btn'" |
| Specify the action and the target: "Close the chat widget by clicking X" | Ambiguous instructions: "Be careful on this page"                  |
| Keep each entry focused on one pattern                                   | Combining multiple patterns in a single entry                      |

***

## Related pages

* [Knowledge Base](/ai-features/knowledge-base.md) — full reference for Knowledge Base features and MCP tools
* [Custom Agents](/ai-features/custom-agents.md) — create specialized AI agents with domain-specific testing instructions
* [AI Test Generation](/ai-features/ai-test-generation.md) — generate test cases from Jira tickets, Figma designs, and more
* [Running Tests](/execution/running-tests.md) — execution options and settings
* [Quickstart Guide](/getting-started/quickstart.md) — create and run your first test case

{% hint style="info" %}
**Reduce false failures with AI that understands your application.** [**Start Free Trial →**](https://app.contextqa.com/register) — Or [**Book a Demo →**](https://contextqa.com/book-a-demo/) to see the Knowledge Base in action with your application.
{% 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 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/knowledge-base-tutorial.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.