The Git Test Management (GTM) System

Introduction

The GTM (Git Test Management) System is a methodology and file structure for managing test artifacts directly in Git repositories using markdown files. It replaces traditional SaaS test management tools (TestRail, Zephyr, qTest) with a Git-native approach that provides true version control, offline access, and seamless integration with development workflows.

Why GTM?

Traditional test management tools create several problems:

• Parallel artifacts — Test documentation lives separately from code, causing drift
• Vendor lock-in — Per-seat licensing fees and proprietary data formats
• No true versioning — Limited history and no branching capabilities
• Offline limitations — Requires internet connectivity to access test cases

GTM solves these by treating test artifacts as code:

• Single source of truth — Tests live alongside the code they verify
• Full Git capabilities — Branching, merging, history, pull request reviews
• Zero licensing costs — Uses standard markdown and Git
• AI-ready format — Markdown optimized for LLM consumption and generation

What This Document Covers

This specification defines:

1. Entity model — The 8 core entities and their relationships
2. Rules — Business rules each entity must follow
3. File structure — Directory organization and naming conventions
4. Templates — Example markdown files for each entity type
5. ID conventions — Standardized identification system
6. Status values — Valid states for each entity

Use this document as both human reference and LLM instruction set for implementing GTM in your projects.

Deliverables

1. article on why
2. entities and relationships
3. rules/spec that llm can follow
4. functions and commands
5. underlying Git architecture

Disclaimer

THESE PROMPTS AND ANY CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

Entities to Model

• Test Plan
• Test Suite
• Test Case
• Test Set
• Test Execution (execution instance of a plan)
• Test Run (results associated with a suite)
• Test Result (result related to a test case)
• Test Cycle?

A Test Set can contain many Test Cases. Test Cases (or a Test Set) can be added to a Test Plan. A Test Plan defines the scope and objectives for a testing effort, linking to one or more Test Suites.

A Test Set is just a way to group some related Test Cases for convenience. A Test Plan has no visibility of a Test Set.

• A Test Set is just used to add Test Cases to a Test Plan more efficiently.

A Test Run is a set of Test Results associated with a specific execution of a Test Suite. Each Test Case executed during the run produces one Test Result, so a Test Run with 10 Test Cases will have 10 Test Results.

Optional Sections

Version Control - add v1, v2, v3 to end of file name and add version field in file

Test Sets - a group of related test cases added to a set to enable eaiser adding to a test suite

Attachments - a folder for entities that have related attachments

Use Submodules - use submodules for common artifacts that you want to share

Archive - use archive to help maintain an active and relevant repository

Unique IDs - Use a centralized ID registry (e.g., _registry.md) to track assigned IDs and prevent duplicates. See “ID Format Conventions” section for details.

Relationships to Model

https://docs.getxray.app/space/XRAYCLOUD/44566802/Terminology

Relationship Diagram

erDiagram
    TEST_PLAN ||--o{ TEST_SUITE : contains
    TEST_PLAN ||--o{ TEST_EXECUTION : triggers
    TEST_SUITE ||--o{ TEST_CASE : groups
    TEST_SUITE ||--o{ TEST_RUN : executes
    TEST_CASE ||--o{ TEST_STEP : has
    TEST_CASE ||--o{ TEST_RESULT : produces
    TEST_RUN ||--o{ TEST_RESULT : generates
    TEST_EXECUTION ||--o{ TEST_RUN : creates
    TEST_RESULT ||--|| TEST_REPORT : aggregates-into

    TEST_PLAN {
        string id PK
        string name
        string version
        string objective
        date start_date
        date end_date
        string status
        string owner
    }

    TEST_SUITE {
        string id PK
        string name
        string description
        string type
        string priority
        string tags
        string plan_id FK
    }

    TEST_CASE {
        string id PK
        string title
        string description
        string preconditions
        string priority
        string automation_status
        string suite_id FK
        string created_by
        date created_date
    }

    TEST_STEP {
        int step_number PK
        string case_id FK
        string action
        string expected_result
        string test_data
    }

    TEST_EXECUTION {
        string id PK
        string plan_id FK
        string environment
        string build_version
        date execution_date
        string executed_by
    }

    TEST_RUN {
        string id PK
        string execution_id FK
        string suite_id FK
        date start_time
        date end_time
        string status
        string runner
    }

    TEST_RESULT {
        string id PK
        string case_id FK
        string run_id FK
        string status
        string actual_result
        int duration_ms
        date timestamp
        string screenshots
    }

    TEST_REPORT {
        string id PK
        date generated_date
        int total_tests
        int passed
        int failed
        int skipped
        float pass_rate
        string report_url
    }

Terminology

Test Plan: A formal plan of the Test Suites intended to have their associated Test Cases executed, where the execution is represented by one or more Test Executions.

Test Suite: A collection of Test Cases organized to be executed together as part of a Test Plan.

Test Case: A specific test scenario composed of multiple Test Steps, each with actions and expected results.

Test Step: A single action within a Test Case, containing the action to perform, expected result, and any test data required.

Test Execution: An assignable, schedulable task to execute one or more Test Suites for a given version/revision, tracking the overall execution effort.

Test Run: A specific instance of running a Test Suite during a Test Execution. Contains execution status and links to Test Results. A Test Suite may have multiple Test Runs across different Test Executions.

Test Result: The outcome of executing a specific Test Case during a Test Run. Each Test Case executed produces one Test Result.

Test Report: An aggregated summary of Test Results, providing metrics such as pass rate, total tests, and execution duration.

Test Set (OPTIONAL): A convenience grouping of Test Cases organized by some logical criteria. Used to efficiently add multiple Test Cases to a Test Plan. A Test Case may belong to multiple Test Sets.

ID Format Conventions

Each entity requires a unique identifier. The following conventions are recommended:

ID Assignment Rules:

1. IDs are manually assigned when creating new artifacts
2. IDs must be unique within their entity type across the entire repository
3. IDs should not be reused after deletion (maintain a registry if needed)
4. For large projects, consider 4-digit numbers (e.g., TC0001) or alphanumeric (e.g., TC-AUTH-001)
5. Test Result IDs are derived from the Test Case ID and Test Run ID combination

Valid Status Values

Each entity has a defined set of valid status values:

Test Plan Status

Test Suite Status

Test Case Status

Test Case Automation Status

Test Execution Status

Test Run Status

Test Result Status

Test Plan Rules

Here’s a full set of statements regarding the TestPlan entity, based on the class diagram and its relationships:

1. A test plan may link to many Test Suites
2. A test plan can be used as an entity to contain many test suites representing a large testing effort
3. A test plan could contain zero test suites (usually when the test plan is first created)
4. A test plan could, in a simple setup, contain just one Test Suite
5. A test plan can be used as a container to identify tests suites (and associated test cases) that should be reported on.
6. A test plan can be associated with multiple test executions that represent different runs or phases of executing the test suites and their associated test cases.

Test Suite Rules

Here’s a full set of statements regarding the TestSuite entity, based on the class diagram and its relationships:

1. A TestSuite is a collection of related TestCases that are intended to be executed together.
2. A TestSuite may link to many TestCases.
3. A TestSuite can be used to organize TestCases based on specific criteria such as functionality, priority, or testing phase.
4. A TestSuite could contain zero TestCases (usually when the TestSuite is first created).
5. A TestSuite could, in a simple setup, contain just one TestCase.
6. A TestSuite can be executed as a unit, which means that all its associated TestCases can be run together.
7. A TestSuite can have a priority level that indicates its importance relative to other suites.
8. A TestSuite can be part of a TestPlan, serving as a component of a larger testing strategy.
9. A TestSuite can exist without being linked to a TestPlan.
10. A TestSuite can be modified to add or remove TestCases as needed throughout the testing process.

• This reflects the functionality of the addTestCase() and removeTestCase() methods.

Test Case Rules

Here’s a full set of statements regarding the TestCase entity, based on the class diagram and its relationships:

1. A TestCase represents a specific scenario or condition that needs to be tested within a TestSuite.
2. A TestCase is associated with one TestSuite, indicating that it belongs to a specific group of related tests.**
3. A TestCase can contain multiple TestSteps, which outline the actions to be performed during the test.
4. A TestCase could contain zero TestSteps (usually when the TestCase is first created).
5. A TestCase could, in a simple setup, contain just one TestStep.
6. A TestCase has a priority level that indicates its importance relative to other test cases.
7. A TestCase can be executed to verify if the software behaves as expected under given conditions.
8. A TestCase can perform validation to check the correctness of the output against expected results.
9. A TestCase can have multiple TestResults, which store the outcomes of its executions.
10. A TestCase can be reused across different TestSuites if applicable, promoting efficiency in test management.
11. A TestCase cannot have associated TestResults unless it is part of a TestSuite, which is executed during a TestRun.

Test Step Rules

Here’s a full set of statements regarding the TestStep entity based on the class diagram and its relationships:

1. A TestStep represents a single action or instruction that is part of a TestCase.
2. A TestStep is associated with one TestCase, indicating that it is a component of that specific test scenario.
3. A TestStep can contain a step number that indicates its sequence within the TestCase.
4. A TestStep can have an action that specifies what needs to be performed during the test.
5. A TestStep can have an expected result that describes what should happen if the step is executed correctly.
6. A TestStep can be executed to perform the action defined in the step.
7. A TestStep can verify the outcome of the action against the expected result.
8. A TestStep can NOT exist without being part of a TestCase because TestSteps are contained WITHIN the TestCase document*

• • Whilst TestSteps are part of a TestCase, and the relationship diagram shows them as being independent entities, TestSteps will actually reside in the same document as the TestCase.

Test Execution Rules

Here’s a full set of statements regarding the TestExecution entity based on the class diagram and its relationships:

1. A TestExecution represents a specific instance of running tests, encompassing the overall execution process for a TestPlan.
2. A TestExecution is associated with one TestPlan, indicating that it corresponds to a particular testing effort.
3. A TestPlan can have multiple TestExecutions, enabling the tracking of various test runs associated with the same testing effort.
4. A TestExecution can have an environment attribute that specifies the testing environment in which the tests are run.
5. A TestExecution can include a build version attribute that indicates the version of the software being tested.
6. A TestExecution can have an execution date that records when the tests were performed.
7. A TestExecution can start the execution process of the tests associated with its TestPlan.
8. A TestExecution can be paused, allowing for temporary halting of the test execution process.
9. A TestExecution can be resumed after being paused, allowing the testing process to continue.
10. A TestExecution can be marked as complete, indicating that all tests have finished running.
11. A TestExecution can be linked to multiple TestRuns, representing different instances of executing tests during the same execution phase.

Test Run Rules

Here’s a full set of statements regarding the TestRun entity based on the class diagram and its relationships:

1. A TestRun represents a specific execution instance of tests that are part of a TestExecution.
2. A TestRun is associated with one TestExecution, indicating that it is a component of that particular execution phase.
3. A TestRun can have a start time that indicates when the test execution began.
4. A TestRun can have an end time that indicates when the test execution completed.
5. A TestRun can have a status attribute that reflects the outcome of the test execution (e.g., passed, failed, in progress).
6. A TestRun can execute the tests associated with its TestExecution, running all relevant TestCases.
7. A TestRun can retrieve the results of the tests that were executed during that run.
8. A TestRun can be linked to multiple TestCases, which are executed as part of that run.
9. A TestRun is essential for tracking the performance and outcomes of tests during a specific execution instance, contributing to overall test reporting.

Test Result Rules

! Here’s a full set of statements regarding the TestResult entity based on the class diagram and its relationships:

1. A TestResult represents the outcome of executing a specific TestCase during a TestRun.
2. A TestResult is associated with one TestCase, indicating that it reflects the result of that particular test scenario.
3. A TestResult can be linked to one TestRun, capturing the context in which the test was executed.
4. A TestResult has a status attribute that indicates the outcome of the test (e.g., passed, failed, blocked).
5. A TestResult can include an actual result attribute that describes what occurred during the test execution.
6. A TestResult can have a duration attribute that records how long the test execution took.
7. A TestResult can record the outcome of the test execution, providing valuable feedback for developers and testers.
8. A TestResult can attach a screenshot or other evidence to support the findings of the test execution.
9. A TestResult is essential for generating reports and metrics related to the testing process, contributing to overall quality assurance.

Test Reports Rules (optional)

Here’s a full set of statements regarding the TestReport entity based on the class diagram and its relationships:

1. A TestReport summarizes the results of test executions, providing an overview of the testing outcomes.
2. A TestReport is associated with multiple TestResults, enabling it to aggregate and present the results of various tests.
3. A TestReport has a total tests attribute that indicates the number of tests included in the report.
4. A TestReport can have a passed attribute that specifies how many tests were successful.
5. A TestReport can include a failed attribute that indicates how many tests did not pass.
6. A TestReport can calculate and present a pass rate, which reflects the percentage of tests that passed out of the total tests executed.

Questions (Resolved)

Q: Should we update the relationship diagram to reflect test steps existing within a test case? A: No. The ER diagram shows Test Step as a separate entity for clarity of the data model. In implementation, Test Steps are embedded within the Test Case markdown document (not separate files). This is documented in the Test Step Rules section.

Q: How does a test run have many test results? A: A Test Run executes all Test Cases in a Test Suite. Each Test Case executed produces one Test Result. So if a Test Suite has 10 Test Cases, a single Test Run of that suite will generate 10 Test Results.

Q: Should we support traceability to defects? A: Yes, at the Test Result level. When a test fails, the Test Result should include a link to any defects raised. Add a “Defects” field to the Test Result template linking to your defect tracking system (e.g., Jira issues).

Q: Should we support traceability to user stories and requirements? A: Yes, at the Test Case level. Each Test Case template includes a “Traceability” section for linking to requirements and user stories. This enables bidirectional traceability between requirements and test coverage.

Aspects to Address

• File Organization: Establish a clear directory structure for organizing test cases (e.g., by feature, module, or sprint) and use consistent naming conventions for test case files.
• Linking to Resources:
  • Images: Use relative paths to link images stored in a designated directory.
  • Execution Records: Create a dedicated section or file for execution logs, linking to them from the test case.
  • Related Test Cases: Link to related test cases using Markdown links for traceability.
• Version Control:
  • Versioning System: Define how to version test cases (e.g., using Git tags or version numbers in the front matter).
  • Change Log: Maintain a CHANGELOG.md file to document changes made to test cases over time.
  • Branching Strategy: Establish a branching strategy for major updates or changes to test cases.
• Libraries:
  • Reusable Test Cases: Maintain a separate directory for reusable test case libraries. Use symbolic links or references in your main test case files to avoid duplication.
  • Version Control for Libraries: Implement version control for the library files, ensuring that updates can be tracked and replicated across different projects.
  • Linking Updates: When a library test case is updated, keep a log of which test cases are dependent on it, so you can easily identify and update affected tests.
• Test Case Metadata: Standardize metadata fields in the front matter (e.g., test case name, ID, assigned to, status) and consider additional fields for tracking execution history or related defects.
• Execution Tracking: Define a clear process for recording test execution results (e.g., using separate execution log files or sections within each test case) and link execution results back to the corresponding test cases.
• Collaboration and Review: Use Git pull requests for reviewing changes to test cases, allowing team members to provide feedback, and establish guidelines for test case writing and updating.
• Parameterization: Decide on a method for parameterizing test cases (e.g., using data tables or separate data files) and document how to use parameters within the test case structure.
• Reuse of Test Cases: Create a library of reusable test cases and define a process for linking to them from specific test cases, considering how updates to the library will propagate to linked test cases.
• Result Aggregation and Reporting: Establish a method for aggregating results from multiple test cases for reporting purposes and consider using scripts to automate the generation of summary reports based on execution results.
• Configuration Management: Document configurations and release versions used in test cases to maintain traceability and consider how to manage different configurations and their impact on test cases.
  • Configuration Management: Document the configurations and releases used for each test case in the Markdown files. This can include fields for “Release Version” and “Configuration.”
  • Matrix of Configurations: Use a matrix or table format to outline which test cases are applicable to which configurations, making it easier to track permutations.
  • Automated Configuration Tracking: Consider integrating scripts that can automatically track and log the configurations used in test executions to maintain consistency.
• Backup and Recovery: Implement a backup strategy for your Git repository to prevent data loss and define a recovery plan in case of accidental deletions or data corruption.
• Training and Documentation: Provide training for team members on how to manage test cases in Git and use Markdown effectively, and maintain documentation outlining best practices and processes for managing test cases.
• Assignment
  • Test Case Structure: Clearly define the ownership of test cases within the Markdown files. You could include fields for “Assigned To” and “Status” at the test case level.
  • Branching for Assignments: Use branches to allocate specific test cases to different QA engineers. This way, individual testers can work independently without conflicts.
  • Tracking Changes: Use comments in pull requests to track discussions about assignments for writing and executing test cases. This allows you to differentiate responsibilities.

File Structure

test-management/
│
├── 1-test-plans/                # Folder for test plan files
│   ├── tp-1.md                  # Test plan document for project 1
│   ├── tp-2.md                  # Test plan document for project 2
│   └── ...
│
├── 2-test-suites/               # Folder for test suite files
│   ├── functional_area_1/       # Subfolder for functional area 1
│   │   ├── ts-1.md              # Test suite document for functional area 1
│   │   ├── ts-2.md              # Test suite document for functional area 1
│   │   └── ...
│   ├── functional_area_2/       # Subfolder for functional area 2
│   │   ├── ts-1.md              # Test suite document for functional area 2
│   │   └── ...
│   └── ...
│
├── 3-test-cases/                # Folder for individual test case files
│   ├── functional_area_1/       # Subfolder for test cases related to functional area 1
│   │   ├── tc-1.md              # Individual test case document
│   │   ├── tc-2.md              # Individual test case document
│   │   └── ...
│   ├── functional_area_2/       # Subfolder for test cases related to functional area 2
│   │   ├── tc-1.md              # Individual test case document
│   │   └── ...
│   └── ...
│
├── 4-test-executions/           # Folder for test execution records
│   ├── te-1.md                  # Test execution document for execution 1
│   ├── te-2.md                  # Test execution document for execution 2
│   └── ...
│
└── 5-test-runs/                 # Folder for test run records
    ├── tr-1.md                  # Test run document for run 1
    ├── tr-2.md                  # Test run document for run 2
    └── ...

test-library/: The root folder containing all test-related documents. README.md: A file that provides an overview of the test library, including guidelines on how to use the structure and format test cases. test_cases/: This new folder contains individual test case files. Each functional area has its own subfolder (e.g., functional_area_1, functional_area_2) to maintain organization. Each test case file (e.g., test_case_1.md) can contain the details of a specific test case, including its title, description, steps, and expected results. test_plans/: This folder contains individual Markdown files for each test plan. Each file can detail the scope, objectives, and overall strategy for testing a specific project or release. test_suites/: Subfolders organized by functional areas (e.g., functional_area_1, functional_area_2). Each subfolder contains Markdown files for various test suites, which group related test cases. test_executions/: This folder contains records of test executions, detailing the environment, build version, and results of each execution. test_runs/: This folder holds documents for individual test runs, capturing the specifics of each execution, including start and end times, status, and any relevant results.

Test Plan Example

# Test Plan: User Acceptance Testing (UAT) - Release 2.0

## Overview
This test plan outlines the testing strategy for the Release 2.0 User Acceptance Testing phase. It covers all functional areas that have been modified or added in this release.

## Metadata
- **ID**: TP001
- **Name**: User Acceptance Testing (UAT) - Release 2.0
- **Version**: 1.0
- **Objective**: Validate that Release 2.0 meets business requirements and is ready for production deployment
- **Start Date**: 2023-10-01
- **End Date**: 2023-10-15
- **Status**: In Progress
- **Owner**: Jane Smith

## Scope
### In Scope
- User authentication functionality (login, logout, password recovery)
- Shopping cart and checkout flow
- User profile management

### Out of Scope
- Payment gateway integration (tested separately)
- Third-party API integrations

## Test Suites
This test plan includes the following test suites:

| Suite ID | Suite Name | Priority | Test Cases |
|----------|------------|----------|------------|
| [TS001](../2-test-suites/authentication/ts-001.md) | User Authentication Tests | High | 4 |
| [TS002](../2-test-suites/cart/ts-002.md) | Shopping Cart Tests | High | 6 |
| [TS003](../2-test-suites/profile/ts-003.md) | User Profile Tests | Medium | 3 |

## Entry Criteria
- All code changes merged to release branch
- Development testing complete
- Test environment configured and accessible
- Test data prepared

## Exit Criteria
- All high-priority test cases executed
- Pass rate >= 95% for critical test cases
- No open Severity 1 or Severity 2 defects
- Sign-off from product owner

## Test Environment
- **Environment**: Staging
- **URL**: https://staging.example.com
- **Browser**: Chrome 118, Firefox 119, Safari 17
- **Mobile**: iOS 17, Android 14

## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| Test environment instability | High | Daily environment health checks |
| Resource availability | Medium | Cross-train team members |

## Execution History
| Execution ID | Date | Status | Pass Rate |
|--------------|------|--------|-----------|
| [TE001](../4-test-executions/te-001.md) | 2023-10-05 | Completed | 92% |
| [TE002](../4-test-executions/te-002.md) | 2023-10-10 | In Progress | - |

## Approvals
| Role | Name | Date | Status |
|------|------|------|--------|
| QA Lead | Jane Smith | 2023-10-01 | Approved |
| Product Owner | John Doe | 2023-10-01 | Approved |

---

**Note**: This test plan will be updated as testing progresses and new information becomes available.

Test Suite Example

# Test Suite: User Authentication Tests

## Overview
This test suite includes all test cases related to the user authentication functionality of the application. It covers login, logout, and password recovery scenarios.

## Metadata
- **ID**: TS001
- **Name**: User Authentication Tests
- **Priority**: High
- **Created Date**: 2023-10-01
- **Last Updated**: 2023-10-10
- **Associated Test Plan**: User Acceptance Testing (UAT) Plan

## Test Cases
This test suite includes the following test cases:

1. [Login with Valid Credentials](../test_cases/functional_area_authentication/test_case_login_valid.md)
   - **Description**: Verify that users can log in with valid credentials.
   - **Priority**: High

2. [Login with Invalid Credentials](../test_cases/functional_area_authentication/test_case_login_invalid.md)
   - **Description**: Verify that users receive an error message when logging in with invalid credentials.
   - **Priority**: High

3. [Password Recovery](../test_cases/functional_area_authentication/test_case_password_recovery.md)
   - **Description**: Verify that users can recover their password using the "Forgot Password" feature.
   - **Priority**: Medium

4. [Logout Functionality](../test_cases/functional_area_authentication/test_case_logout.md)
   - **Description**: Verify that users can log out successfully.
   - **Priority**: High

## Execution Notes
- Ensure that the application is deployed in the testing environment before executing the test cases.
- Test data should be prepared in advance for successful login scenarios.

## Related Documentation
- [Test Plan: User Acceptance Testing (UAT)](../test_plans/test_plan_uat.md)
- [Test Execution Log](../test_executions/execution_log_1.md)

---

**Note**: This test suite may be updated as new features are added or existing functionalities are modified.

Test Case Example

# Test Case: Login with Valid Credentials

## Overview
Verify that a registered user can successfully log in to the application using valid credentials.

## Metadata
- **ID**: TC001
- **Title**: Login with Valid Credentials
- **Suite**: [User Authentication Tests (TS001)](../2-test-suites/authentication/ts-001.md)
- **Priority**: High
- **Automation Status**: Automated
- **Created By**: Jane Smith
- **Created Date**: 2023-09-15
- **Last Updated**: 2023-10-01
- **Tags**: authentication, login, smoke-test

## Preconditions
- User account exists in the system with known credentials
- Application is accessible at the test URL
- User is not currently logged in (session cleared)

## Test Data
| Field | Value |
|-------|-------|
| Username | testuser@example.com |
| Password | TestPass123! |

## Test Steps

| Step | Action | Expected Result | Test Data |
|------|--------|-----------------|-----------|
| 1 | Navigate to the login page | Login page is displayed with username and password fields | URL: /login |
| 2 | Enter valid username in the username field | Username is accepted and displayed in the field | testuser@example.com |
| 3 | Enter valid password in the password field | Password is accepted and masked in the field | TestPass123! |
| 4 | Click the "Login" button | User is authenticated and redirected to the dashboard | - |
| 5 | Verify the dashboard is displayed | Dashboard page loads with user's name visible in the header | - |

## Postconditions
- User is logged in and session is active
- User can access authenticated pages

## Traceability
- **Requirement**: REQ-AUTH-001 - Users shall be able to authenticate with valid credentials
- **User Story**: US-101 - As a user, I want to log in to access my account

## Related Test Cases
- [TC002: Login with Invalid Credentials](./tc-002.md)
- [TC004: Logout Functionality](./tc-004.md)

## Notes
- This test case is part of the smoke test suite and should be executed with every build
- Password field should mask input characters

---

**Automation Reference**: `tests/authentication/login.spec.ts:12`

Test Execution Example

# Test Execution: User Authentication Tests

## Overview
This document records the execution details for the User Authentication Tests test suite, including the environment, execution date, and a summary of test runs.

## Metadata
- **ID**: TE001
- **Test Suite**: User Authentication Tests (TS001)
- **Environment**: Staging
- **Build Version**: 1.0.0
- **Execution Date**: 2023-10-12

## Test Run Summary
This execution includes the following test runs:

| Test Run ID | Start Time           | End Time             | Status    | Total Test Cases | Passed | Failed |
|--------------|----------------------|----------------------|-----------|------------------|--------|--------|
| TR001        | 2023-10-12 10:00 AM  | 2023-10-12 10:30 AM  | Completed | 4                | 3      | 1      |

## Execution Notes
- Ensure that the application is deployed in the testing environment before executing the test cases.
- Test data should be prepared in advance for successful login scenarios.

---

**Note**: This execution document will be updated as more test runs are performed.

Test Run Example

# Test Run: User Authentication Tests - Run 1

## Overview
This document details the first run of the User Authentication Tests test suite as part of the test execution TE001.

## Metadata
- **ID**: TR001
- **Test Execution ID**: TE001
- **Start Time**: 2023-10-12 10:00 AM
- **End Time**: 2023-10-12 10:30 AM
- **Status**: Completed

## Test Cases Executed
| Test Case ID | Test Case Title                      | Status   | Duration (minutes) | Notes                        |
|---------------|--------------------------------------|----------|---------------------|------------------------------|
| TC001         | Login with Valid Credentials         | Passed   | 5                   |                              |
| TC002         | Login with Invalid Credentials       | Failed   | 7                   | Error message not displayed. |
| TC003         | Password Recovery                    | Passed   | 8                   |                              |
| TC004         | Logout Functionality                 | Passed   | 5                   |                              |

## Results Summary
- **Total Test Cases Executed**: 4
- **Passed**: 3
- **Failed**: 1
- **Duration**: 30 minutes
- **Pass Rate**: 75%

## Attachments
- [Screenshots of Test Failures](../attachments/failure_screenshots.png)
- [Detailed Logs](../logs/test_run_logs.txt)

---

**Note**: This run log will be used for future reference and analysis.

Test Documentation Management Guide For Human

Purpose

This guide aims to provide a structured approach to managing test documentation, ensuring clarity, traceability, and efficiency in the testing process.

Folder Structure

Maintain a clear and organized folder structure for your test documentation. The recommended structure is as follows:

test-management/
│
├── 1-test-plans/                # Folder for test plan files
│   ├── tp-1.md                  # Test plan document for project 1
│   ├── tp-2.md                  # Test plan document for project 2
│   └── ...
│
├── 2-test-suites/               # Folder for test suite files
│   ├── functional_area_1/       # Subfolder for functional area 1
│   │   ├── ts-1.md              # Test suite document for functional area 1
│   │   ├── ts-2.md              # Test suite document for functional area 1
│   │   └── ...
│   ├── functional_area_2/       # Subfolder for functional area 2
│   │   ├── ts-1.md              # Test suite document for functional area 2
│   │   └── ...
│   └── ...
│
├── 3-test-cases/                # Folder for individual test case files
│   ├── functional_area_1/       # Subfolder for test cases related to functional area 1
│   │   ├── tc-1.md              # Individual test case document
│   │   ├── tc-2.md              # Individual test case document
│   │   └── ...
│   ├── functional_area_2/       # Subfolder for test cases related to functional area 2
│   │   ├── tc-1.md              # Individual test case document
│   │   └── ...
│   └── ...
│
├── 4-test-executions/           # Folder for test execution records
│   ├── te-1.md                  # Test execution document for execution 1
│   ├── te-2.md                  # Test execution document for execution 2
│   └── ...
│
└── 5-test-runs/                 # Folder for test run records
    ├── tr-1.md                  # Test run document for run 1
    ├── tr-2.md                  # Test run document for run 2
    └── ...

Document Relationships

1. Test Plans:

   • Reference associated test suites.
   • Include links to relevant documentation, such as execution records.

2. Test Suites:

   • List all test cases included in the suite.
   • Reference the associated test plan.
   • Include links to test execution records where results are documented.

3. Test Cases:

   • Include a reference to the associated test suite.
   • Optionally, consider adding links back to the test suites for traceability, but assess if the complexity is manageable.
   • Clearly outline pre-conditions, test steps, expected results, and post-conditions.

4. Test Executions:

   • Document details regarding the execution of test suites.
   • Include summaries of the test cases executed, their statuses, and overall results.

5. Test Runs:

   • Summarize the results of executed test cases during a specific run.
   • Reference the associated test execution to provide context.

Best Practices

• Consistency: Maintain a consistent format across all documents to enhance readability and usability.
• Clear Naming Conventions: Use clear and descriptive names for test plans, suites, cases, executions, and runs. Use prefixes (e.g., tp-, ts-, tc-, te-, tr-) to indicate document types.
• Regular Updates: Ensure that all documentation is kept up to date, especially after changes to test cases or execution results.
• Review and Approval: Establish a review and approval process for key documents, particularly test plans and cases, to ensure quality and completeness.
• Centralized Traceability: Consider maintaining a centralized traceability matrix if managing bidirectional links becomes cumbersome. This can provide a clear mapping of all test cases to their respective suites and plans without cluttering individual documents.

Conclusion

This guide provides a structured approach to managing test documentation, enhancing clarity and traceability within your testing process. By following these best practices and maintaining an organized folder structure, your team can improve the efficiency of test management and execution.