Draft · v0.1

QA & Testing knowledge

This is a profile within the OQA layer: a domain vocabulary that lets query agents (and quality tools such as bugAgent) navigate software-quality knowledge — stories, test cases, automated checks, bugs, media artifacts, performance, accessibility, security, and exploratory testing.

Like everything in OQA, this profile adds conventions only on top of OKF and the OQA overlay: recommended type values and a handful of optional custom frontmatter keys. Every concept on this page is still a plain OKF concept whose only required field is a non-empty type. Relationships use the OQA relations convention — a YAML list of { predicate, target } where target is a bundle-absolute path. Retrieval hints reuse OQA's summary, keywords, and aliases; freshness and stable identity reuse OKF's timestamp and resource. All of it is SHOULD-level, and consumers MUST tolerate unknown types and unknown keys.

Still a valid OKF/OQA bundle Nothing here raises the conformance bar. The type values below are recommendations; the custom keys (acceptance_criteria, steps, severity, remedies, wcag_criteria, …) are OKF extension keys that consumers may ignore and MUST preserve on round-trip. A bundle that uses none of these conventions is still a conformant OKF bundle; if anything here appears to conflict with OKF, OKF wins.

Draft — this will change This profile is part of OQA v0.1. Type names, key names, and relationship predicates are expected to change as the vocabulary is exercised against real query agents and tools. Do not treat any of it as stable yet.

Concept type vocabulary

The profile defines nine recommended type values. Load and stress testing fold into Performance Test via its kind key rather than introducing a separate type.

type value	Describes
`User Story`	A unit of desired behaviour with acceptance criteria; the thing tests verify.
`Test Case`	A manual or scripted check — preconditions, steps, expected results.
`Automated Test`	An executable check on a web, mobile, or API surface, with a script and run history.
`Bug Report`	A defect with severity, repro steps, root cause, remedies, and attached media.
`Media`	A screenshot, recording, or other captured asset; also a cross-cutting attachment convention.
`Performance Test`	A page-load, load, or stress measurement with metrics and thresholds.
`Accessibility Test`	A WCAG conformance check with criteria and violations.
`Security Test`	A SAST/DAST/dependency/secrets scan with findings.
`Exploratory Session`	A timeboxed, charter-driven manual investigation that produces findings.

1 · User Story

A User Story captures desired behaviour and the acceptance_criteria that define "done". It is the anchor that test cases verify. (Net-new for OQA — bugAgent reserves a user_story link type but has no backing table, so this profile gives stories a first-class shape.)

Key	Meaning
`type`	Always `User Story`.
`title`	Short story name.
`description`	The narrative, often "As a … I want … so that …".
`acceptance_criteria`	YAML list of strings — the conditions that must hold for the story to be accepted.
`status`	Lifecycle, e.g. `draft` · `ready` · `in-progress` · `done`.
`tags`	OKF tags for grouping (epic, area, release).

Typical relations: verified_by → one or more Test Case concepts.

---
type: User Story
title: Customer can reset a forgotten password
description: >
  As a returning customer, I want to reset my password from the login
  page so that I can regain access without contacting support.
acceptance_criteria:
  - A "Forgot password?" link is visible on the login page.
  - Submitting a registered email sends a reset link within 60s.
  - The reset link expires after 24 hours and is single-use.
  - After a successful reset the user is signed in automatically.
status: ready
tags: [auth, account, release-7]
summary: >
  Self-service password reset from the login page: email a single-use,
  24-hour reset link and sign the user in on success.
keywords: [password reset, forgot password, account recovery, reset link]
aliases: [forgot password flow, password recovery story]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: verified_by
    target: /test-cases/password-reset-happy-path.md
  - predicate: verified_by
    target: /test-cases/password-reset-expired-link.md
---

# Customer can reset a forgotten password

A returning customer resets their password from the login page and is
signed in on success. Covered by the
[happy-path](/test-cases/password-reset-happy-path.md) and
[expired-link](/test-cases/password-reset-expired-link.md) test cases.

2 · Test Case

A Test Case is a concrete check. Its steps are a list of { action, expected } pairs — the exact shape bugAgent stores in test_cases.steps. It verifies a story and may be implemented by an automated test.

Key	Meaning
`type`	Always `Test Case`.
`preconditions`	State that must hold before the steps run.
`steps`	YAML list of `{ action, expected }` — what the tester does and what should happen.
`priority`	`low` · `medium` · `high` · `critical` (maps to bugAgent `priority_rank`).
`status`	`draft` · `active` · `deprecated`.
`test_type`	`functional` · `regression` · `smoke` · `integration` · `performance` · `security` · `usability` · `exploratory`.

 Typical relations: verifies → User Story; automated_by → Automated Test.
 ---
type: Test Case
title: Password reset — happy path
preconditions: A registered account exists with a verified email.
steps:
  - action: Open the login page and click "Forgot password?"
    expected: The reset-request form is shown with an email field.
  - action: Enter the registered email and submit.
    expected: A confirmation message appears; a reset email arrives within 60s.
  - action: Open the reset link and set a new valid password.
    expected: The password is accepted and the user lands signed-in on the dashboard.
priority: high
status: active
test_type: functional
summary: >
  End-to-end happy path for self-service password reset: request link,
  follow it, set a new password, and confirm auto sign-in.
keywords: [password reset, login, reset link, smoke]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: verifies
    target: /stories/password-reset.md
  - predicate: automated_by
    target: /automated-tests/password-reset.web.md
---

# Password reset — happy path

Verifies the [password reset story](/stories/password-reset.md). Automated by
the [Playwright web test](/automated-tests/password-reset.web.md).
 3 · Automated Test
 An Automated Test is an executable check. The surface key separates the three families bugAgent automates: web (Playwright, via automations), mobile (Appium/Maestro, via mobile_automations), and api. script and last_run are resource-style URIs pointing at the script and at the most recent run/result (e.g. a CI run URL or a stored video).
   Key Meaning
 
  type Always Automated Test.
 surface web | mobile | api — which surface the test drives.
 framework playwright | appium | maestro | k6 | …
 language Script language, e.g. typescript · python · yaml (Maestro flows).
 script Resource URI of the script source.
 schedule Cron or cadence (maps to bugAgent automation_schedules.cron_expression).
 last_run Resource URI of the most recent run/result.
 status draft · active · paused · archived.
 
 
 Typical relations: automates → Test Case. Mobile note: set surface: mobile and a mobile framework (appium / maestro); web tests use surface: web with playwright.
 ---
type: Automated Test
title: Password reset (web, Playwright)
surface: web
framework: playwright
language: typescript
script: https://github.com/acme/qa/blob/main/specs/password-reset.spec.ts
schedule: "0 6 * * *"
last_run: https://app.bugagent.com/automations/ar_5f12/runs/run_9a31
status: active
summary: >
  Nightly Playwright check that drives the full password-reset happy path
  on the web app and records a video and trace artifact per run.
keywords: [playwright, web automation, password reset, nightly]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: automates
    target: /test-cases/password-reset-happy-path.md
---

# Password reset (web, Playwright)

A nightly Playwright spec that automates the
[happy-path test case](/test-cases/password-reset-happy-path.md). For the
mobile equivalent, a sibling concept would set `surface: mobile` with
`framework: appium` or `maestro`.
 4 · Bug Report
 A Bug Report is a defect. It carries repro steps, root cause, environment, and — net-new for OQA — a remedies list of candidate fixes or workarounds (bugAgent stores remediation on security/probe findings but not on bug reports, so this fills the gap). Media attaches via the media key (see the next section).
   Key Meaning
 
  type Always Bug Report.
 severity How bad — s1–s4 (bugAgent) or critical/high/medium/low.
 status e.g. new · confirmed · in-progress · resolved · closed.
 resolution fixed · duplicate · will-not-fix · works-as-designed · cannot-reproduce · …
 root_cause regression · integration · environment · missing-requirement.
 environment Browser/OS/device/viewport/URL where it reproduces.
 steps_to_reproduce YAML list of ordered repro steps.
 remedies YAML list of candidate fixes or workarounds (net-new for OQA).
 media YAML list of { resource, caption } attachments (see Media).
 
 
 Typical relations: relates_to → Test Case; blocks → User Story; found_in → Exploratory Session.
 ---
type: Bug Report
title: Reset link expires immediately on Safari iOS
severity: s2
status: confirmed
root_cause: environment
environment:
  browser: Safari
  os: iOS 18.2
  device: iPhone 15
  url: https://app.example.com/reset
steps_to_reproduce:
  - Request a password reset on Safari iOS.
  - Open the emailed reset link within one minute.
  - Observe the "link expired" error before any input.
remedies:
  - Stop normalizing the token timestamp to device-local time; compare in UTC.
  - Workaround for users — open the reset link in Chrome until the fix ships.
media:
  - resource: https://cdn.example.com/bugs/reset-expired-ios.png
    caption: Expired-link error on first open (Safari iOS).
summary: >
  On Safari iOS the password reset link reports "expired" immediately
  because the token expiry is compared in device-local time instead of UTC.
keywords: [password reset, safari ios, token expiry, timezone, s2]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: relates_to
    target: /test-cases/password-reset-expired-link.md
  - predicate: blocks
    target: /stories/password-reset.md
  - predicate: found_in
    target: /sessions/auth-mobile-exploration.md
---

# Reset link expires immediately on Safari iOS

The reset token expiry is compared in device-local time rather than UTC, so
the link looks expired on first open. Blocks the
[password reset story](/stories/password-reset.md). Found during the
[mobile auth session](/sessions/auth-mobile-exploration.md).

![Expired-link error on Safari iOS](https://cdn.example.com/bugs/reset-expired-ios.png)
 5 · Media
 A Media concept is a captured asset — screenshot, recording, log, image. A Media concept SHOULD carry a resource URI pointing at the asset (without one it has nothing to reference), but as everywhere in OQA, type stays the only required field. In bugAgent these live in the bug-attachments / test-case-attachments buckets and on run rows as screenshots / video_url / trace_url.
   Key Meaning
 
  type Always Media.
 resource SHOULD be present — URI to the asset (image, video, log).
 media_type MIME type, e.g. image/png · video/webm.
 alt Short alternative text for accessibility.
 caption Human-readable caption.
 captured_at When the asset was captured.
 
 
 Cross-cutting convention. Any concept MAY attach media two ways: inline in its markdown body (image/link syntax), and/or via a custom media key — a YAML list of { resource, caption }. Use a standalone Media concept when the asset is worth indexing on its own (and you want a stable resource id); use the inline/media-key form for attachments that only matter in context (as the Bug Report above does).
 ---
type: Media
title: Expired-link error on Safari iOS
resource: https://cdn.example.com/bugs/reset-expired-ios.png
media_type: image/png
alt: Safari iOS showing a "link expired" error on the reset page.
caption: Captured on first open of the reset link, before any input.
captured_at: 2026-06-23T18:42:00Z
keywords: [screenshot, safari ios, password reset, expired link]
timestamp: 2026-06-24T00:00:00Z
---

# Expired-link error on Safari iOS

Standalone evidence asset, referenced by the
[Safari iOS bug report](/bugs/reset-link-expires-ios.md).
 The two inline forms, for a concept that does not need a standalone Media concept:
 # In any concept body — inline markdown image
![Expired-link error](https://cdn.example.com/bugs/reset-expired-ios.png)

# In any concept frontmatter — the custom media key
media:
  - resource: https://cdn.example.com/runs/run_9a31/video.webm
    caption: Full Playwright run recording.
  - resource: https://cdn.example.com/bugs/reset-expired-ios.png
    caption: Expired-link error screenshot.
 6 · Performance Test
 A Performance Test measures speed and capacity. The kind key folds load and stress testing in alongside page-load — no separate type. bugAgent splits this across Lighthouse (page-load: lcp_ms, ttfb_ms, …) and k6 (load/stress: k6_rps, k6_p95_ms, …).
   Key Meaning
 
  type Always Performance Test.
 tool lighthouse | k6 | …
 kind page-load | load | stress.
 metrics Observed values, e.g. { lcp, ttfb, p95_latency, rps }.
 thresholds Pass/fail budgets (drive auto-bug creation in bugAgent).
 target Resource URI of the page or endpoint under test.
 run Resource URI of the run/result.
 
 
 Typical relations: covers → the target surface (page, endpoint, or the User Story whose performance it guards).
 ---
type: Performance Test
title: Checkout API — sustained load
tool: k6
kind: load
target: https://api.example.com/v1/checkout
run: https://app.bugagent.com/performance/runs/pr_77c2
metrics:
  rps: 480
  p95_latency: 612
  error_rate: 0.004
thresholds:
  p95_latency: 800
  error_rate: 0.01
summary: >
  Sustained k6 load test of the checkout endpoint at ~480 rps; p95 latency
  612ms against an 800ms budget, error rate well under threshold.
keywords: [k6, load test, checkout, p95, throughput, stress]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: covers
    target: /endpoints/checkout-api.md
---

# Checkout API — sustained load

Drives ~480 rps against the checkout endpoint. A `kind: stress` variant
ramps past capacity to find the breaking point; both share this type.
 7 · Accessibility Test
 An Accessibility Test records WCAG conformance. The wcag_criteria and violations keys give structured success-criterion data — net-new for OQA, since bugAgent only stores an aggregate Lighthouse accessibility score, not individual criteria.
   Key Meaning
 
  type Always Accessibility Test.
 standard e.g. WCAG 2.2.
 level A | AA | AAA.
 wcag_criteria YAML list of criterion ids, e.g. ["1.4.3", "2.4.7"].
 violations YAML list of { criterion, impact, element }.
 target Resource URI of the page/component tested.
 
 
 Typical relations: covers → target; raises → Bug Report for each violation worth tracking.
 ---
type: Accessibility Test
title: Login page — WCAG 2.2 AA audit
standard: WCAG 2.2
level: AA
target: https://app.example.com/login
wcag_criteria: ["1.4.3", "2.4.7", "4.1.2"]
violations:
  - criterion: "1.4.3"
    impact: serious
    element: "button.cta (contrast 3.1:1, needs 4.5:1)"
  - criterion: "2.4.7"
    impact: moderate
    element: "input#email (no visible focus indicator)"
summary: >
  WCAG 2.2 AA audit of the login page: two violations — insufficient CTA
  contrast (1.4.3) and a missing focus indicator on the email field (2.4.7).
keywords: [wcag, accessibility, contrast, focus visible, aa]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: covers
    target: /pages/login.md
  - predicate: raises
    target: /bugs/login-cta-contrast.md
---

# Login page — WCAG 2.2 AA audit

Two AA violations on the [login page](/pages/login.md). The contrast issue
is tracked as a [bug report](/bugs/login-cta-contrast.md).
 8 · Security Test
 A Security Test records a scan and its findings. The findings entries carry typed cwe and owasp ids — net-new structure for OQA, since bugAgent stores these as free-text in reference_url/category rather than dedicated columns.
   Key Meaning
 
  type Always Security Test.
 scan_type SAST | DAST | dependency | secrets.
 findings YAML list of { title, severity, cwe, owasp }.
 target Resource URI of the app, endpoint, or repo scanned.
 run Resource URI of the scan run.
 
 
 Typical relations: raises → Bug Report for findings above the bug threshold.
 ---
type: Security Test
title: Checkout API — DAST scan
scan_type: DAST
target: https://api.example.com/v1/checkout
run: https://app.bugagent.com/security/runs/sr_31ab
findings:
  - title: Reflected XSS in error message
    severity: high
    cwe: CWE-79
    owasp: A03:2021-Injection
  - title: Missing rate limiting on auth attempts
    severity: medium
    cwe: CWE-307
    owasp: A07:2021-Identification-and-Authentication-Failures
summary: >
  DAST scan of the checkout endpoint surfaced a high-severity reflected XSS
  (CWE-79) and a missing auth rate limit (CWE-307).
keywords: [dast, xss, rate limiting, owasp, cwe, security scan]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: raises
    target: /bugs/checkout-reflected-xss.md
---

# Checkout API — DAST scan

Two findings on the [checkout endpoint](/endpoints/checkout-api.md); the XSS
is escalated to a [bug report](/bugs/checkout-reflected-xss.md).
 9 · Exploratory Session
 An Exploratory Session is a timeboxed, charter-driven investigation. It maps to bugAgent's explorations (the charter: focus_areas, instructions, auth_config) and exploration_findings (the observations). It produces bug reports.
   Key Meaning
 
  type Always Exploratory Session.
 charter The mission — what to explore and why.
 timebox Duration allotted, e.g. 90m.
 environment Build/URL/device the session ran against.
 observations YAML list of notes and findings recorded during the session.
 areas Tags for the surfaces touched (auth, checkout, mobile, …).
 
 
 Typical relations: produced → one or more Bug Report concepts.
 ---
type: Exploratory Session
title: Mobile auth flows — exploratory session
charter: >
  Probe the sign-in, sign-up, and password-reset flows on mobile Safari and
  Chrome for edge cases around tokens, timezones, and session expiry.
timebox: 90m
environment:
  build: web 9.41
  device: iPhone 15 (Safari iOS 18.2), Pixel 8 (Chrome)
areas: [auth, mobile, password-reset]
observations:
  - Reset link reports "expired" immediately on Safari iOS — looks timezone-related.
  - Sign-up succeeds but the welcome toast is clipped on small viewports.
  - Re-using a consumed reset link shows a generic 500 rather than a clear message.
summary: >
  90-minute exploratory pass over mobile auth flows; surfaced a timezone-driven
  reset-link expiry on Safari iOS plus two lower-severity UX issues.
keywords: [exploratory testing, mobile, auth, session, charter, timebox]
timestamp: 2026-06-24T00:00:00Z
relations:
  - predicate: produced
    target: /bugs/reset-link-expires-ios.md
---

# Mobile auth flows — exploratory session

A timeboxed pass over mobile auth. The most serious observation became the
[Safari iOS reset bug](/bugs/reset-link-expires-ios.md).
 Relationships at a glance
 The types link into a single quality graph. A User Story is verified_by Test Cases; each Test Case verifies the story and is automated_by an Automated Test (which in turn automates the case across a web, mobile, or api surface). A Bug Report relates_to a Test Case, blocks a story, and is found_in an Exploratory Session — which produced it. Performance, Accessibility, and Security tests cover a target and raise Bug Reports when they fail. Media attaches anywhere, inline or via the media key.
   From predicate To
 
  User Story verified_by Test Case
 Test Case verifies User Story
 Test Case automated_by Automated Test
 Automated Test automates Test Case
 Bug Report relates_to Test Case
 Bug Report blocks User Story
 Bug Report found_in Exploratory Session
 Performance Test covers target surface
 Accessibility Test covers / raises target / Bug Report
 Security Test raises Bug Report
 Exploratory Session produced Bug Report
 
 
 Next
 For the conventions this profile builds on — recommended type values, the relations shape, and the summary/keywords/aliases retrieval hints — see The OQA layer. For complete, copy-paste bundles see Examples, and for the base field reference see the Open Knowledge Format.

Key	Meaning
`type`	Always `Automated Test`.
`surface`	`web` \| `mobile` \| `api` — which surface the test drives.
`framework`	`playwright` \| `appium` \| `maestro` \| `k6` \| …
`language`	Script language, e.g. `typescript` · `python` · `yaml` (Maestro flows).
`script`	Resource URI of the script source.
`schedule`	Cron or cadence (maps to bugAgent `automation_schedules.cron_expression`).
`last_run`	Resource URI of the most recent run/result.
`status`	`draft` · `active` · `paused` · `archived`.

Key	Meaning
`type`	Always `Bug Report`.
`severity`	How bad — `s1`–`s4` (bugAgent) or `critical`/`high`/`medium`/`low`.
`status`	e.g. `new` · `confirmed` · `in-progress` · `resolved` · `closed`.
`resolution`	`fixed` · `duplicate` · `will-not-fix` · `works-as-designed` · `cannot-reproduce` · …
`root_cause`	`regression` · `integration` · `environment` · `missing-requirement`.
`environment`	Browser/OS/device/viewport/URL where it reproduces.
`steps_to_reproduce`	YAML list of ordered repro steps.
`remedies`	YAML list of candidate fixes or workarounds (net-new for OQA).
`media`	YAML list of `{ resource, caption }` attachments (see Media).

Key	Meaning
`type`	Always `Accessibility Test`.
`standard`	e.g. `WCAG 2.2`.
`level`	`A` \| `AA` \| `AAA`.
`wcag_criteria`	YAML list of criterion ids, e.g. `["1.4.3", "2.4.7"]`.
`violations`	YAML list of `{ criterion, impact, element }`.
`target`	Resource URI of the page/component tested.

Key	Meaning
`type`	Always `Media`.
`resource`	SHOULD be present — URI to the asset (image, video, log).
`media_type`	MIME type, e.g. `image/png` · `video/webm`.
`alt`	Short alternative text for accessibility.
`caption`	Human-readable caption.
`captured_at`	When the asset was captured.

Key	Meaning
`type`	Always `Performance Test`.
`tool`	`lighthouse` \| `k6` \| …
`kind`	`page-load` \| `load` \| `stress`.
`metrics`	Observed values, e.g. `{ lcp, ttfb, p95_latency, rps }`.
`thresholds`	Pass/fail budgets (drive auto-bug creation in bugAgent).
`target`	Resource URI of the page or endpoint under test.
`run`	Resource URI of the run/result.

Key	Meaning
`type`	Always `Security Test`.
`scan_type`	`SAST` \| `DAST` \| `dependency` \| `secrets`.
`findings`	YAML list of `{ title, severity, cwe, owasp }`.
`target`	Resource URI of the app, endpoint, or repo scanned.
`run`	Resource URI of the scan run.

Key	Meaning
`type`	Always `Exploratory Session`.
`charter`	The mission — what to explore and why.
`timebox`	Duration allotted, e.g. `90m`.
`environment`	Build/URL/device the session ran against.
`observations`	YAML list of notes and findings recorded during the session.
`areas`	Tags for the surfaces touched (auth, checkout, mobile, …).

From	predicate	To
User Story	`verified_by`	Test Case
Test Case	`verifies`	User Story
Test Case	`automated_by`	Automated Test
Automated Test	`automates`	Test Case
Bug Report	`relates_to`	Test Case
Bug Report	`blocks`	User Story
Bug Report	`found_in`	Exploratory Session
Performance Test	`covers`	target surface
Accessibility Test	`covers` / `raises`	target / Bug Report
Security Test	`raises`	Bug Report
Exploratory Session	`produced`	Bug Report