Knowledge Base

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.

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

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.

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.

Interactive demo: give the AI agent application context

See how a team records application-specific guidance once and makes it available to the ContextQA execution agent without embedding that guidance in every test case.

What to notice

• Each entry describes one recurring application behavior in direct, actionable language.
• Workspace or run scoping controls where the context applies.
• Knowledge Base instructions explain how to use named data or secrets; they do not store the secret values themselves.

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.

---

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 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:

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.

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.

---

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

{
  "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 Test Generation
• Running Tests
• Test Plans
• System Configuration
• MCP: list_knowledge_bases

70% less human effort with AI test generation and self-healing. Book a Demo → — See AI generate, execute, and maintain tests for your application.