How to Turn E2E Tests into Readable Markdown Catalogs for AI-Assisted Development

---

The Role of E2E Tests in the AI Coding Era

When AI writes code, implementation diffs alone do not prove that user-visible behavior is still correct. E2E tests verify workflows from the outside, so they can protect product behavior without depending on internal implementation details.

📑Table of Contents

1. The Role of E2E Tests in the AI Coding Era
2. Why Behavior Gets Buried in Test Code
3. Generating Tests and Catalogs from a Kotlin DSL
4. Practical Effects of a Markdown Behavior Catalog
5. Fit with Playwright Best Practices
6. Operating Rules and Secondary Benefits
7. Frequently Asked Questions
8. Summary
9. X Post Hashtags

The Loglass example shows a useful next step: turning E2E behavior into readable Markdown catalogs. For humans, this makes the expected behavior easier to review. For AI tools, it provides a compact specification that can be used as context during coding.

Playwright’s documentation also encourages tests that describe user-facing behavior through locators and assertions. That philosophy fits well with a catalog approach, where the test is not only an execution artifact but also a shareable behavior contract.

---

Why Behavior Gets Buried in Test Code

As E2E suites grow, important product rules become buried in test files. Error conditions, missing-value handling, and calculation expectations often require reading multiple code paths before the behavior becomes clear.

This increases review cost. Reviewers must understand implementation changes, test changes, and business rules at the same time. With AI-generated code, they also need to check whether the AI misunderstood the intended behavior.

A Markdown catalog separates that concern. It lets the team review behavior as a list of inputs, actions, and expected outcomes. This makes it easier to distinguish a real specification change from a refactor.

---

Generating Tests and Catalogs from a Kotlin DSL

The key is avoiding manual Markdown maintenance. In the Loglass approach, a Kotlin DSL declares behavior cases, then both E2E tests and Markdown documentation are generated from the same source.

The declaration can include the behavior contract, input data, initial state, and expected result. Once those are structured, they can drive both test execution and documentation. A pre-commit hook and CI check can fail the build when generated files are stale.

This also improves AI-assisted development. Instead of repeatedly explaining the same behavior in prompts, the team can provide a generated catalog as a stable source of truth.

---

Practical Effects of a Markdown Behavior Catalog

Markdown catalogs are especially useful when test cases include many combinations. Tables make calculation logic, edge cases, and expected values easier to scan.

Perspective	Test Code Only	Markdown Catalog
Behavior overview	Requires reading files	Visible in tables
PR review	Implementation-oriented	Behavior diff is clear
AI context	Often needs code snippets	Can use compact expectations
Stale docs	Manual risk	CI can detect drift

Because Markdown renders directly in GitHub, the catalog becomes reviewable by engineers, QA, and product managers. E2E tests become a shared specification asset rather than a hidden implementation detail.

---

Fit with Playwright Best Practices

Playwright encourages locators that reflect what users see, such as roles and labels. This keeps tests close to user behavior rather than implementation details. Markdown catalogs follow the same direction.

Playwright’s auto-waiting and web-first assertions also help keep tests stable. Stable tests make generated catalogs more trustworthy. A flaky E2E suite cannot become a reliable specification source.

The catalog does not replace the test runner. It adds a readable specification layer on top of the execution layer.

---

Operating Rules and Secondary Benefits

The most important operating rule is simple: do not edit the generated catalog by hand. Change the DSL or structured source, regenerate the catalog, and let CI verify consistency.

A useful side effect is better AI context. A generated behavior catalog can be passed to AI tools during coding or refactoring. For large codebases, this is often more efficient than asking the AI to infer behavior from the entire source tree.

Teams do not need to migrate every E2E test at once. Start with workflows that change often, contain important business rules, or involve calculations where expected values matter.

---

Frequently Asked Questions

Q: Why convert E2E tests into Markdown?

A: It makes behavior easy to review and share with both humans and AI tools.

Q: Can the Markdown be written manually?

A: It is safer to generate it from the same source as the test, because manual documentation drifts quickly.

Q: Does this require Playwright?

A: No. The core idea works with any E2E stack if inputs, actions, and expected results are structured.

Q: How does this help AI coding?

A: It gives the AI a clear behavior contract, reducing the chance that generated code breaks existing expectations.

Q: Where should a team start?

A: Start with workflows that change often, have complex business rules, or include calculation-heavy expectations.

---

Related articles:

• AutoReserve AI Booking Service Sparks Restaurant Complaints Over Endless Calls and Unauthorized Listings
• Beyond Individual Prompting: Building Team-Scale AI-Driven Development Loops
• Beyond “AI Writes Your SQL” — Building a Production-Grade Analytics Platform with dbt

Summary

The goal of a Markdown E2E catalog is not prettier documentation. The goal is to give humans and AI the same readable behavior contract.

By generating tests and catalogs from a shared DSL and enforcing freshness in CI, teams can avoid duplicate maintenance while improving behavior visibility. As AI-assisted coding grows, this kind of outside-in behavior guarantee becomes more important.

---

X Post Hashtags

{
  "tags": [
    "#E2ETesting",
    "#AI",
    "#Playwright",
    "#SoftwareTesting",
    "#DeveloperExperience"
  ],
  "source_section": "Title + Summary",
  "source_fingerprint": "sha256:e2e-markdown-catalog-5574",
  "generated_at": "2026-07-01T10:10:00+00:00"
}