The Problem: Disconnected Test Catalogs

Most development teams maintain their automated test specifications—Playwright or Robot Framework specs—alongside their product code. This is standard practice. However, manual test cases often reside in entirely separate locations. They might be in spreadsheets, cloud-based Test Management Systems (TMS), or wiki pages that quickly become outdated after the initial release. This fragmentation creates a significant disconnect.

The consequence is that tracking automation coverage becomes a quarterly, if not more infrequent, guessing game. The catalog of manual tests and the executable specifications never share a stable identifier, making direct correlation impossible. This gap hinders effective quality assurance, slows down release cycles, and makes it difficult to understand the true state of test coverage.

The Solution: A Unified Git Repository

The most effective solution is to bring both manual and automated test definitions into the same Git repository. By treating manual test cases as files within this repository, you enable standard text-matching capabilities. This approach bypasses the need for custom AI integrations within test tools. Any Integrated Development Environment (IDE) agent or simple script can then perform linking by matching identifiers.

This strategy creates a single source of truth for all testing artifacts. It fosters a more integrated and transparent testing process, where manual and automated tests are not siloed but are part of a cohesive suite. This unification simplifies maintenance, improves visibility, and ensures that test coverage metrics are accurate and readily available.

Implementing the Unified Approach

The core idea is to structure your Git repository to house both layers of your testing suite. Automated tests typically reside in directories like tests/ or e2e/, depending on team conventions. The key innovation is how manual cases are managed.

Manual Cases as YAML Files: Manual test cases are stored as YAML files. The convention is to place these files under specific directories: .gitoza-lite/test/cases/ for use with VS Code or Cursor extensions, or .gitoza/test/cases/ for the desktop application. The critical element here is that the filename, excluding the .yaml extension, serves as the stable, unique ID for that test case. For example, a file named user_login_flow.yaml would have the ID user_login_flow.

Automated Tests: These continue to live in their established locations within the repository. The linking mechanism relies on the stable IDs derived from the manual case filenames. When a manual case ID matches a pattern or identifier within an automated test script (e.g., a comment, a specific variable, or a naming convention), a link is established.

This setup allows for straightforward linking through simple text matching. If a manual test case ID is mentioned in an automated test script or vice-versa, the connection is immediately apparent and machine-readable. This eliminates the ambiguity and manual effort previously required to correlate disparate test artifacts.

Linking Mechanisms and IDE Integration

With manual test cases as YAML files and automated tests in their usual spots, linking becomes a matter of convention and tooling. An IDE agent or a custom script can scan the repository. It looks for instances where a manual test case ID (the filename without extension) appears within the automated test code or in associated metadata.

For instance, an automated Playwright test file might contain a comment like # Manual Case ID: user_login_flow. Similarly, a Robot Framework test might use a variable or keyword that incorporates the ID. The linking tool or IDE plugin can then parse these instances and establish a bidirectional link between the manual case file and the automated test script.

This approach is powerful because it leverages existing developer workflows and tools. Developers working in their IDE can see the linked manual test cases directly alongside their automation code, providing immediate context. This visibility is crucial for understanding the scope and purpose of automated tests and for identifying gaps in coverage.

Benefits of a Unified Test Repository

Consolidating manual test cases into the same Git repository as automated tests offers several key advantages:

  • Improved Visibility and Traceability: All test artifacts are in one place, providing a clear overview of test coverage and enabling easy traceability from requirements to execution.
  • Accurate Coverage Metrics: Linking manual cases to automated specs allows for precise calculation of automation coverage, moving beyond quarterly guesses to real-time insights.
  • Simplified Maintenance: Changes to product features can be reflected across both manual and automated test definitions more easily when they are co-located. Updates to a manual case ID can be propagated to its linked automated tests efficiently.
  • Enhanced Collaboration: Developers, QA engineers, and product managers can collaborate more effectively when all testing information is accessible and synchronized within the same version control system.
  • Reduced Tooling Overhead: Eliminates the need for separate, potentially expensive, TMS solutions for managing the catalog of manual tests if the Git repo is sufficient. It also avoids custom integrations between test execution tools and external management systems.
  • Leveraging Existing IDEs: Developers can use familiar IDE features for navigation, linking, and code analysis, as manual test cases are treated as standard files.

This method transforms test management from a fragmented, labor-intensive process into an integrated, efficient workflow. By adopting this unified repository strategy, teams can significantly improve their testing quality, speed, and overall development efficiency.