Where Are the Unit Tests Located in the awesome-claude-code Repository?

All unit tests for awesome-claude-code reside in the top-level tests/ directory, which houses a comprehensive pytest suite that validates every major component from resource validation to README generation.

The awesome-claude-code repository organizes its verification logic in a dedicated test package that mirrors the production codebase structure. Understanding where these tests are located and how they map to source modules is essential for contributing to or extending the project's functionality.

The tests/ Directory Structure

All unit tests live in the tests/ package at the repository root. This directory contains a comprehensive pytest suite that validates every major component of the project—resource validation, link processing, table-of-contents anchoring, style selector logic, Git/GitHub utilities, CSV handling, and README generation.

The test hierarchy mirrors the production modules exactly, making it straightforward to locate the corresponding tests for any source file.

Mapping Test Files to Production Modules

Each test file follows the test_*.py naming convention and maps directly to its production counterpart in src/:

• test_validate_single_resource.py covers src/resource_validation.py, checking single-resource validation paths and primary/secondary handling.

• test_validate_links.py validates src/link_validation.py, including HTTP date parsing, stale-threshold logic, overrides, and GitHub-specific enrichment.

• test_toc_anchor_validation.py tests src/toc_anchor.py by extracting and comparing anchors from GitHub READMEs versus generated TOCs.

• test_style_selector_paths.py verifies src/style_selector.py, ensuring asset-path calculations work correctly for root versus alternative style READMEs.

• test_sort_resources.py covers src/sort_resources.py, ensuring deterministic sorting by category, sub-category, and display name.

• test_resource_utils.py tests src/resource_utils.py, covering CSV appending, default values, and error handling.

• test_github_utils.py validates src/github_utils.py against various GitHub URL forms including blob, tree, raw, and gist formats.

• test_git_utils.py covers src/git_utils.py, validating command-existence checks and subprocess error handling.

• test_generate_readme.py and related files like test_readme_generators_minimal_visual.py verify src/readme_generator.py, confirming both minimal and visual README generators emit the expected structure.

Running the Test Suite

Since all test files follow the test_*.py naming convention, pytest automatically discovers them when invoked from the repository root.

To run the complete test suite:

# From the repository root

pytest

To execute a specific test file:

pytest tests/test_github_utils.py

Test Implementation Examples

The suite uses standard pytest patterns. For example, in tests/test_github_utils.py, the parse_github_url function is tested against various URL formats:

def test_parse_github_url_blob_with_slash_branch() -> None:
    url = "https://github.com/owner/repo/blob/main/path/to/file.md"
    parsed = parse_github_url(url)
    assert parsed.repo == "owner/repo"
    assert parsed.branch == "main"
    assert parsed.path == "path/to/file.md"

Adding New Tests

When adding functionality to a new helper like src/my_helper.py, create a corresponding file in the tests/ directory:

# tests/test_my_helper.py

from src.my_helper import useful_function

def test_useful_function_returns_true():
    assert useful_function() is True

Place the new test_my_helper.py file directly in the tests/ folder alongside existing modules like test_git_utils.py and test_validate_links.py.

Summary

• All unit tests for awesome-claude-code are located in the tests/ directory at the repository root.
• The test structure mirrors the src/ production modules, with files named test_*.py corresponding to their source counterparts.
• The pytest framework automatically discovers tests when running pytest from the repository root.
• Key test modules cover resource validation, link checking, Git/GitHub utilities, TOC anchoring, and README generation.
• New tests should follow the existing naming convention and placement in the tests/ folder.

Frequently Asked Questions

Where exactly are the test files stored in awesome-claude-code?

All test files are stored in the top-level tests/ directory within the repository root. This folder contains the entire pytest suite, with each test file following the test_*.py naming pattern to ensure automatic discovery by the test runner.

How do I run the unit tests locally?

Navigate to the repository root and execute pytest to run the full suite, or specify an individual file with pytest tests/test_github_utils.py. The test runner automatically picks up all files matching the test_*.py pattern in the tests/ folder according to the project configuration.

Which test file covers the README generation logic?

The test_generate_readme.py file and its variants like test_readme_generators_minimal_visual.py validate the src/readme_generator.py module. These tests confirm that both minimal and visual README generators produce the expected output structure and handle edge cases correctly.

What testing framework does awesome-claude-code use?

The project uses pytest as its testing framework. All unit tests are written as standard pytest functions, and the framework discovers them automatically based on the test_*.py naming convention in the tests/ directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}