> 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.md). # Knowledge Base ## Quick answer How to create and use Knowledge Base entries to teach ContextQA's AI agent how to handle application-specific UI patterns, consent banners, popups, and test-specific instructions. Use this page to understand when the capability applies, complete its user-facing workflow, and verify the expected result. ## What this page covers {% 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. {% hint style="danger" %} **A Knowledge Base is not a secret store.** Never paste a production password, API token, session cookie, private key, OTP seed, or recovery code into an entry. Knowledge Base text becomes AI context and is visible to users who can view or edit the entry. Put the value in an approved **Password** or **Vault** environment variable (or another organization-approved secret manager), and let the Knowledge Base describe *when and how to use the named secret* without containing the secret itself. {% endhint %} *** ## 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 data | `On a payment form in the sandbox environment, use the approved payment-test values selected from the environment data picker. Never submit a live card or bank account.` | | Two-factor authentication | `If the staging sign-in flow requests a one-time code, retrieve it through the approved test-mailbox or TOTP workflow. Do not ask a person to paste a reusable seed into the test.` | | 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. ### Referencing credentials safely Use this division of responsibility: | Store here | Example | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Knowledge Base** | `For the staging admin flow, use the credential fields named stageAdminUser and stageAdminPassword from the selected environment.` | | **Environment & Data → environment variable** | The actual username as a String and password as a **Password** or **Vault** value. | | **Test step** | Insert the approved value with the environment-data picker; do not type the literal credential into the action text. | Secret values are masked where the selected secret type supports masking, but names, descriptions, Knowledge Base text, and literal step text are not automatically redacted. Before sharing screenshots, videos, logs, traces, exported data, or AI output, verify that no secret is visible. Access to an entry follows workspace permissions; keep entries scoped to the smallest appropriate workspace and remove obsolete instructions. If a test needs an OTP, magic link, or temporary token, retrieve it at runtime from an approved test-only source. Store only the resulting short-lived value in a runtime variable, and never preserve the reusable seed or long-lived token in the Knowledge Base. *** ## 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 unused entry | Click the three-dot menu → Delete, then confirm the warning | | Disable without deleting | Not directly supported — delete and recreate when needed | | Duplicate | Not directly supported — create a new entry with similar content | ContextQA blocks deletion when a knowledge base is still referenced by a test case, test plan, or organization default. Remove or replace those references first, then retry the deletion. If an older result or record points to a knowledge base that no longer exists, the UI displays **None** rather than a stale identifier. {% hint style="warning" %} Deleting a knowledge base is permanent. Before deletion, search shared test cases and plans for references and confirm that **Settings → Organization Setting → AI Configuration → Default Knowledge Base** does not select it. {% endhint %} *** ## 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) * [Test Plans](/web-testing/test-plans.md) * [System Configuration](/administration/system-configuration.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 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.md?ask=&goal= ``` `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.