Skip to content

pedrovgs/UseCaseCoverage

BranchesTags

Repository files navigation

🚀 Use Case Coverage (UCC)

License Rust

🛡️ Use Case Coverage is a simple but powerful developer tool designed to bridge the gap between feature specifications and test implementations. It helps you track, calculate, and visualize your test coverage against declared use cases, features, and bugs using a simple yet strict .ucc YAML format.

🤖 AI-Ready Quality Assurance: In the age of AI-driven development, tracking the coverage of your AI agents is vital for maintaining software excellence. UseCaseCoverage (UCC) empowers you to measure that impact with precision and ease. ✨

🧞 Privacy First & Zero Infrastructure: UseCaseCoverage is designed to run entirely on your local machine or within your CI pipeline. There is no backend, no data is ever uploaded to any server, and your specifications remain completely private and secure. Since it is a standalone CLI tool, there is no infrastructure to host or maintain.

🤔 Why is code coverage not enough? You may think your coverage is above 80% of the lines of code, yet you still don't know how many distinct real-world use cases your tests cover, or even which tests cover specific use cases. You probably know the code you don't cover with automated tests but you probably don't know how many real world use cases are impacted because of this. Code coverage is designed for software engineers; use case coverage is designed for people.

🖼️ Screenshots

Dashboard Inventory
Dashboard Inventory
Feature Detail Coverage Gaps
Feature Detail Coverage Gaps
Tags
Tags

📦 Installation

One-liner (Linux & macOS):

curl -fsSL https://raw.githubusercontent.com/pedrovgs/UseCaseCoverage/main/install.sh | bash

Homebrew (macOS): Assuming you have Homebrew installed:

brew tap pedrovgs/tap
brew install use_case_coverage_cli

Alternatively, you can install it in a single command:

brew install pedrovgs/tap/use_case_coverage_cli

Linux (.deb): Download the latest .deb package from the releases page and install it using:

sudo dpkg -i use-case-coverage-cli_*.deb

🛠 Usage

Tracking your coverage with UCC follows a simple three-step workflow:

  1. 📝 Define your Specs: Write your features, use cases, bugs, and regressions in the simple .ucc YAML format anywhere in your project.
  2. 🏷️ Annotate your Tests: Include the unique ID of your artifacts in your test code (as a comment or within a string). UCC scans your codebase to find these matches automatically. You can annotate any type of test even in monorepos using different proramming languages and frameworks.
  3. 🚀 Generate & Analyze: Run ucc report to compute coverage metrics and generate a beautiful, interactive dashboard. You can execute ucc locally or integrate it in your CI/CD pipeline.

⌨️ CLI Options

UCC provides several flags to customize its behavior:

Option Description
-i, --input <path> Root directory to scan for .ucc files (default: current directory).
-o, --output <path> Output directory for reports or file for linting.
--as, --additional-sources <path> Additional directories to scan for .ucc and test files (repeatable).
-s, --single Disable recursive .ucc file discovery (only scan top-level directory).

🏷️ Annotation Examples

UCC is language-agnostic. You can annotate your tests by simply including the artifact ID anywhere in your test file (e.g., in a comment, test name, or metadata). A single test can reference multiple artifacts using comma or space separators:

🍎 Swift (XCTest / Swift Testing)

// You can mention multiple IDs in a comment
// ucc-feat-1, ucc-feat-2
@Test("Successful login flow for ucc-feat-3")
func testLoginFlow() {
    ...
}

🔷 TypeScript (Jest / Mocha / Vitest)

// IDs can be part of the test description separated by commas or spaces
test('should authenticate user (ucc-feat-1, ucc-feat-2)', () => {
    ...
});

🦀 Rust (Cargo Test)

#[test]
fn test_artifact_parsing_ucc_feat_1() {
    // Artifact IDs in test names are automatically discovered
    ...
}

☕ Kotlin (JUnit / Spek)

@Test
fun testSecureLogin() {
    /* Multiple IDs in a block comment: ucc-feat-1 ucc-feat-2 */
    ...
}

Note on IDs: Artifact and Feature IDs cannot contain commas, as commas are reserved as separators for multi-artifact annotations in test files.

📄 The .ucc Format

UseCaseCoverage relies on .ucc files—standard YAML files that live alongside your code.

✨ Basic Structure

schema_version: "1.0"

feature:
  id: user-authentication
  title: User Authentication
  created_at: "2026-05-10"
  description: >
    Handles user login, signup, and session management.

related_features: []

artifacts:
  - id: ucc-feat-1
    title: Successful login with valid credentials
    priority: high
    created_at: "2026-05-10"
    steps:
      - Enter username
      - Enter password
      - Click submit
    expected:
      - User is redirected to dashboard

  - id: ucc-feat-2
    type: bug
    title: Login fails on slow connections
    priority: highest
    created_at: "2026-05-10"
    related: [ucc-auth-001]
    tags: [auth, secure]
    platforms: [web, android, ios]
    coverage_gap_reason: "Impossible to test on Android automatically"

### 🧬 Tags & Platforms Inheritance

To avoid repetition, you can define `tags` and `platforms` at the **feature level**. All artifacts within that `.ucc` file will automatically inherit them unless they provide their own overrides.

```yaml
feature:
  id: user-authentication
  tags: [auth]
  platforms: [web, ios]
...
artifacts:
  - id: ucc-feat-1 # Inherits tags: [auth] and platforms: [web, ios]
    ...
  - id: ucc-feat-2
    platforms: [android] # Overrides platforms to [android], still inherits tags: [auth]

### ✅ Linting `.ucc` files

Ensure your specifications are perfect before generating reports. The `lint` command validates your `.ucc` files recursively, checking for:
- Correct YAML schema.
- **Unique IDs**: Ensures no two features or artifacts share the same ID across the entire project.
- **Unique File Names**: Ensures `.ucc` file names are unique to prevent reporting conflicts.

```bash
ucc lint

Tip: You can specify an input directory or an output file for automated audits:

ucc report --input ./specs --output output_folder

📊 Generating Visual Reports

Transform your YAML files into a stunning, interactive HTML dashboard that visualizes your project's health. The report includes:

  • Coverage Metrics: Global and feature-level coverage percentage.
  • Artifact Inventory: A searchable list of all your use cases, bugs, and regressions.
  • Coverage Gaps: A dedicated section with a word cloud visualization of common reasons for missing coverage.
ucc report

By default, reports are neatly organized in .ucc/reports/YYYY-MM-DD_HH-MM-SS.

🧩 Key Components

  • Use Cases: Standard artifacts capturing user requirements.
  • Bugs & Regressions: Explicitly tracked items with type: bug or type: regression.
  • Cross-Platform Tracking: Granularly track coverage across android, apple, web, windows, or any other platform you define in the platforms field.
  • Coverage Gaps: Document known missing coverage with coverage_gap_reason to keep the team informed about missing automated coverage.

🤖 GitHub Actions Integration

Automate your coverage tracking with a simple workflow. UseCaseCoverage can be installed on GitHub Actions runners (Ubuntu or macOS) using our universal installation script.

name: Use Case Coverage
on: [push]

jobs:
  coverage:
    runs-on: ubuntu-latest # or macos-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install ucc
        run: curl -fsSL https://raw.githubusercontent.com/pedrovgs/UseCaseCoverage/main/install.sh | bash
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Optional but recommended to avoid rate limits
        
      - name: Lint UCC files
        run: ucc lint
        
      - name: Generate Report
        run: ucc report
        
      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: ucc-report
          path: .ucc/reports/

Tip

For a working example of installation via Homebrew or Debian packages in CI, check out our verification workflow.

👨‍💻 Developer Guide

🛠 Prerequisites

  • Rust stable toolchain (rustup + cargo)
  • Git

🚀 Initial Setup

rustup toolchain install stable
rustup default stable
rustup component add rustfmt clippy

🧪 Workspace Commands

Command Action
cargo fmt --all Format the entire codebase
cargo clippy --workspace Run the linter
cargo test --workspace Run all unit and e2e tests
cargo run -p use_case_coverage_cli -- report Run the CLI locally

Developed By

Follow me on X Add me to Linkedin

📄 License

Copyright 2026 Pedro Vicente Gómez Sánchez

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

About

CLI tool to measure and collect use case coverage for any app or repository!

Resources

Readme

License

Apache-2.0 license
Activity

Stars

9 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 5

v0.5.0 Latest
May 16, 2026
+ 4 releases

Sponsor this project

 
Learn more about GitHub Sponsors

Packages

 
 
 

Contributors

Languages