Why Manual Test Cases Should Live in YAML

Most teams still treat manual test cases as rows in a SaaS database. That worked when cases were written slowly, reviewed rarely, and automation lived in a separate silo. It works less well now. AI can draft cases from screenshots and user stories in minutes. Automation lives next to application code. QA and dev share the same PRs. Auditors ask where test data lives and who changed what.

In that world, test cases are data - and the format you choose matters as much as the tool UI. The durable direction is tests as code: plain YAML files in version control, with a thin local layer for humans to browse, run, and review. Not because databases are evil, but because git + YAML matches how we already work with code, AI, and compliance.

AI is good at YAML - and YAML keeps your data yours

LLMs are unusually good at structured text: YAML front matter plus a Markdown body is a sweet spot. Give the model a schema (title, tags, priority, steps, expected result) and a screenshot or user story, and you get a draft case in one pass. That matters for more than speed:

• Boundary cases - ask the model what you might have missed; it can reason about the scenario, not just paraphrase the story.
• Consistency - the same format every time makes batch generation and review predictable.

The deeper point is data ownership. Cases in a vendor DB are convenient until they are not: export limits, API friction, another system to secure, another place sensitive scenarios live. Local YAML in your repo is trivial for AI to read (including Cursor, Copilot, or whatever you use next), diff, and update - without shipping your test catalog to a third party. For many teams, that is a real security and efficiency win - not ideology.

Manual YAML beside automation makes coverage measurable

When manual cases and automated tests sit in the same repository, a few things become boring in a good way:

• Tag a case automated: true and point params at a Playwright or Selenium path - one file, one id.
• Automation coverage is a script or an AI pass away: scan specs, match case ids or titles, flip flags, report gaps.
• Automation rate stops being a quarterly spreadsheet exercise.

Example - a manual case linked to a Playwright spec:

---
title: Login with valid credentials
tags: [smoke, auth, playwright]
automated: true
params:
  playwright: tests/auth/login.spec.ts
---

Steps

1. Open the login page
2. Enter valid credentials

Expected result

User is redirected to the dashboard.

The case filename is the case id. Tags and params give automation a handle without a separate traceability spreadsheet.

Git diffs are a review surface, not a workaround

When AI generates cases at volume, git diff is the review UI. You see exactly what changed: new case, edited steps, tag added, automated flipped. PR review works the same as for application code. Test runs can be YAML too - one file per run, case paths and results inline - so run history is also versioned. Git's time machine means you can see what you tested three years ago, not what a database happened to retain after a migration. For QA leads, that is the difference between "we changed the suite" and "here is the diff."

Local files, audit trails, and data sovereignty

YAML on disk fits a lot of compliance expectations without extra product features:

• Offline / on-prem - no requirement to sync cases or runs to a vendor cloud.
• Tamper evidence - commit hashes and (if you use them) GPG-signed commits attach authorship to changes; faking "we always had this test" is harder than editing a row with admin access in a hosted DB.
• Data sovereignty - the canonical copy lives in your repo, branch, and backup policy.

A database can be compliant. So can files. The difference is whether compliance is bolted on or native to how the artifact is stored.

The UX problem - and why a local renderer matters

The honest drawback: YAML is code. It is precise and diff-friendly; it is not fun to click through for a full-day test run. That gap is real. It is also why file-based test management tends to ship a local UI that reads and writes the same YAML files on disk. The goal is not "no database anywhere" - it is no hosted database as the system of record.

A desktop client may keep a derived SQLite index or shadow clone under local app data for fast search and navigation; that cache is rebuildable from the files and never replaces what is committed in git. A VS Code extension can go further and touch only the workspace files - no separate index at all. Browse suites, edit cases, execute runs; YAML in the repo stays the source of truth.

The workflow that tends to work:

• Cases and test runs follow branches - QA reviews case changes in the PR like any other change.
• Devs stay in the IDE - open a test repository view, skim cases next to the fix they are working on.
• After a bugfix, assign a case to a tester in the same branch and ship case + fix in one PR.

YAML holds the source of truth; the renderer is the lens. Tests as code with a usable surface - not a replacement for thinking about structure.

What I am not claiming

• YAML in git is not magic - you still need conventions, CODEOWNERS, and review discipline.
• AI-generated cases still need human review - diff-friendly format just makes that cheaper.
• This is not "dump TestRail tomorrow" for every org - migration cost and habit matter.

I am claiming that if you want AI-assisted authoring, shared repos with automation, PR-based review, and strong auditability, file-based YAML cases age better than another hosted test database.

Try it

If you want to see this workflow in practice:

• Gitoza - the full platform: desktop client, git sync, review workflows, automation pipelines, and dashboards for the whole team.
• Gitoza Lite on GitHub - open-source VS Code extension; cases under .gitoza-lite/test/cases/ and runs under .gitoza-lite/test/run/.
• Install from the VS Code Marketplace - open a repo, run Gitoza: Open Test Repository, create a project, commit the YAML.

Lite works directly on workspace YAML with no local index. Gitoza Desktop adds sync, dashboards, and a derived SQLite cache under ~/.gitoza/ - still rebuilt from the same files on disk. Both treat YAML in git as the source of truth.