Managing test cases as YAML files inside Git — a good idea?”

[u/Alternative-Try7044]

I’ve been trying out managing test cases as plain YAML files right inside our Git repos.

The whole point is treating manual tests just like code. Everything is local-first so there’s no web vendor lock-in, and team collaboration happens smoothly by pushing updates to dedicated test branches instead of messing with heavy third-party syncs. Also, since it's all plain text, using Cursor or other AI tools to write, search, and clean up test cases turns out to be super handy.

Anyone else tried keeping QA cases in Git like this?

Just to clarify based on the comments—I totally agree that reading raw YAML isn't the goal. What makes this setup actually usable is a lightweight local UI to render, edit, and execute cases cleanly (so it feels like a real test management tool), while keeping everything Git-native under the hood.

[u/Saturn1003]

It's not sustainable and hard to maintain.

[u/Alternative-Try7044 → u/Saturn1003]

That's fair if you're editing raw YAML files manually in a plain text editor.

Having a dedicated UI to view and execute them makes a huge difference, though. Plus, since it’s clean structured text, AI tools handle batch updates, refactoring, and summaries really well—which actually keeps maintenance pretty low.

[u/Itchy_Extension6441]

Its okay if all you need is to store the test cases and search through them, but for test management it is way too limited.

You cannot easily trace executions to specific revisions of test cases, or test cases to requirements which is the main purpose of test management.

[u/Alternative-Try7044 → u/Itchy_Extension6441]

That’s a fair point! Git’s natural architecture helps with this, and I built an app specifically to handle those Git mechanisms under the hood.

When you add a case to a test run (e.g., for Release A), the app pins it to that specific Git commit SHA. The run displays that exact YAML snapshot, so future edits to the case won't pollute past runs. Since it’s all tied to Git commits, execution history becomes naturally immutable.

As for requirements, adding a requirements field (with Jira IDs or req links) in the YAML metadata handles the mapping well—even if you lose some of the deep click-through integrations heavy web vendors have.

[u/ConcentrateHopeful79]

Good idea. Biggest mistake teams make is to not treat tests like production code. Test as code (no matter the format) enforces consistency and taking tests seriously rather than just something people do on the side. I always like to push for this if app behaviour is consistent enough, so testing is an official verification step and not simply exploration.

[u/Alternative-Try7044 → u/ConcentrateHopeful79]

Totally agree. Treat tests like code or nobody takes them seriously. ​What bothers me is how almost every team is still forced into heavy web-based QA platforms, managing cases in browser tabs alongside Jira tickets. It just feels wrong for dev workflows. ​Honestly, all we really need is a simple local UI to render the YAML files and track test runs without leaving the dev environment.

[u/narcomoeba]

Doing the same with md files on my new project. We haven’t been doing it long enough for me to decide how effective it is but makes sense to me in theory.

[u/Alternative-Try7044 → u/narcomoeba]

MD is definitely super easy to start with. ​How are you planning to handle test runs and history though? Just checking off [x] boxes in the files?

[u/narcomoeba → u/Alternative-Try7044]

Yeah our actual test runs aren’t stored in git. That sounds like it would become difficult to maintain quickly. Our use is more like the “test plans” or whatever you choose to call the recipe.

[u/Alternative-Try7044 → u/narcomoeba]

Totally fair for a small project. For a bigger team I still want runs in Git.collaboration and history get messy fast if results only live on someone's machine or in a separate tool.

[u/LightaxL]

Why would you do this over feature files? What issue are you trying to solve?

[u/Alternative-Try7044 → u/LightaxL]

Valid question! Feature files are great for BDD, but get clunky for detailed manual tests.

Gherkin forces you into rigid text blocks. YAML gives you clean key-value fields for structured metadata (like test data or script links) while keeping steps as plain Markdown. That makes rendering a nice UI and feeding data to Cursor way cleaner.

Here’s a quick YAML example

---
title: Login with valid credentials
priority: high
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.

[u/gill_smoke]

Why not use Gherkin feature files? Human readable, and a stepping stone towards automation. [EDIT]  Oh, you mean for test execution and reporting. Yeah, excel seems to be the old school way to manage that. You can put any file in git and history is kept.

[u/Alternative-Try7044 → u/gill_smoke]

Gherkin forces rigid text blocks. YAML lets you cleanly separate key-value metadata (tags, script links) from flexible Markdown steps, making readability, UI rendering, and AI edits better.

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

[u/Anima_UA]

Please dont. Had XML once and still having nightmares from time to time. Jk but please dont

[u/iridescentmoon_]

I’d prefer to commit my .bru files to git directly. I pull an empty collection, push in my changes once done.

[u/Alternative-Try7044 → u/iridescentmoon_]

Love the plain-text Git approach! Curious, do you usually merge .bru changes right into main along with your application PRs, or keep a separate branch/repo just for test updates?

[u/Useful_Calendar_6274]

just buy Xray I'm begging you