Knowledge Base

The Knowledge Base (KB) is the source of truth that drives everything VigilQA generates. Well-structured KB entries produce better tests.

What is the Knowledge Base?

The Knowledge Base is a structured repository of expected application behaviours. It is organised into domains (functional areas of your application) containing scenarios (individual test cases described in plain language). The generation pipeline reads KB scenarios and transforms them into executable test scripts.

Think of the KB as a living specification: when your application evolves, you update the KB, and VigilQA regenerates the affected tests automatically.

Structure

Domains

A domain maps to a bounded functional area of your application. Examples: Authentication, User Profile, Checkout, Products API, Admin Dashboard. Each project can have unlimited domains.

Each domain has:

• Domain ID — a short slug used in test IDs (e.g. auth, checkout)
• Domain name — human-readable label shown in the dashboard
• Base URL(s) — optional list of URLs/paths this domain primarily covers
• Scenarios — one or more test scenarios

Scenarios

Each scenario describes one behaviour that should be verifiable by a test. A scenario consists of:

Field	Required	Description
id	Yes	Unique identifier within the domain. Convention: DOMAIN-NNN (e.g. AUTH-001)
title	Yes	Short plain-language description of what is being tested
steps	Yes	Ordered list of actions a user or API caller takes
expected	Yes	Observable outcome that confirms the scenario passes
module	No	Override which module generates the script. Defaults to project-level module settings.
tags	No	Labels for filtering test plans (e.g. smoke, regression)
priority	No	high, medium, or low. Used by CoverageGap agent reporting.

Example KB entries

# Domain: Authentication
domain: auth
base_urls:
  - /login
  - /register
  - /forgot-password

scenarios:
  - id: AUTH-001
    title: "Successful login with valid credentials"
    tags: [smoke, regression]
    priority: high
    steps:
      - Navigate to /login
      - Enter valid email address
      - Enter correct password
      - Click the "Sign In" button
    expected: >
      User is redirected to /dashboard.
      Navigation bar shows the user's name.
      Session cookie is set.

  - id: AUTH-002
    title: "Login fails with incorrect password"
    priority: high
    steps:
      - Navigate to /login
      - Enter registered email
      - Enter incorrect password
      - Click "Sign In"
    expected: >
      Page remains on /login.
      Error message "Invalid email or password" is visible.
      No session cookie is set.

  - id: AUTH-003
    title: "Password reset email is sent"
    priority: medium
    steps:
      - Navigate to /forgot-password
      - Enter registered email address
      - Click "Send reset link"
    expected: >
      Success message "Check your email" is displayed.
      Confirmation email is sent to the address entered.

Writing good scenarios

Be specific about the expected outcome

Vague expected outcomes produce weak assertions. Instead of "user is logged in", write "user is redirected to /dashboard and the navigation bar shows the user's first name". The more specific the expected outcome, the more valuable the generated assertions.

One behaviour per scenario

Each scenario should verify one thing. Avoid bundling multiple flows into a single scenario ID — split them. This makes failures easier to diagnose and improves the quality of the generated test script.

Write steps as observable actions

Steps should describe what a user or API caller does, not implementation details. Use language like "Navigate to /login", "Click the Sign In button", "Send POST to /api/auth/login with body {"email":"...","password":"..."}".

Use consistent terminology

Use the same names for UI elements across scenarios (e.g. always "Sign In button", not sometimes "Login button"). AppExplorer uses this terminology to locate the correct DOM elements.

Extract from Document

If your team already has test plans or feature specifications written in Word, PDF, or Markdown, the Extract from Document feature can bootstrap your KB in minutes instead of hours.

Navigate to Knowledge Base → Extract from Document and upload your file (.docx, .pdf, or .md). The AI reads the document and splits it into the standard KB file set:

• application.yaml — business rules, validations, domain logic
• ui_pages.yaml — web UI pages, fields, and user flows
• api_specs.yaml — API endpoints and expected responses
• product_knowledge.yaml — product context and non-functional requirements

After extraction, each file appears as a preview card with:

• An editable YAML textarea so you can correct the output before saving
• Error badges for missing required fields (file will not be auto-checked for save)
• Warning badges for missing recommended fields (file is auto-checked; save is allowed)

Only files you explicitly check are written to disk. Nothing is saved until you click Save Selected. You can re-run extraction with the same document as many times as needed.

Updating the KB

The KB can be updated at any time through the dashboard's KB editor. After updating scenarios, you can re-run the generation pipeline for affected domains only — you don't need to regenerate the entire project.

Deleted scenarios are flagged in the next generation run and the corresponding scripts are archived (not deleted) pending your review.