README

TestLink

Framework-Agnostic Test Traceability for PHP

TestLink creates bidirectional links between your tests and production code. Know exactly which tests cover each method, and which methods each test exercises.

Supports both Pest and PHPUnit - use whichever testing framework you prefer, or both in the same project.

Features

• Framework Agnostic - Works with Pest, PHPUnit, or both
• Bidirectional Linking - Link tests to methods AND methods to tests
• Two Link Types - Coverage links (linksAndCovers) and traceability-only links (links)
• Sync Validation - Detect missing or orphaned links
• Auto-Sync - Generate link calls from #[TestedBy] attributes
• Standalone CLI - Use testlink command independently of test runner
• JSON Export - CI/CD integration

Quick Start

Installation

# Production dependency - attributes for production code
composer require testflowlabs/test-attributes

# Dev dependency - CLI tools, scanners, validators
composer require --dev testflowlabs/testlink

Why two packages?

• test-attributes must be a production dependency because #[TestedBy], #[LinksAndCovers], and #[Links] attributes are placed on production classes. PHP needs these attribute classes available when autoloading your production code.
• testlink can be a dev dependency because it only provides CLI tools (testlink report, testlink validate, testlink sync) that run during development.

Link from Production Code (Recommended)

// app/Services/UserService.php
use TestFlowLabs\TestingAttributes\TestedBy;

class UserService
{
    #[TestedBy(UserServiceTest::class, 'it creates a user')]
    #[TestedBy(UserServiceTest::class, 'it validates email format')]
    public function create(array $data): User
    {
        // ...
    }
}

Link from Tests

Pest

// tests/Unit/UserServiceTest.php

// Link + Coverage (triggers coverage tracking)
test('it creates a user')
    ->linksAndCovers(UserService::class.'::create');

// Link only (traceability without coverage)
test('it creates a user integration')
    ->links(UserService::class.'::create');

// Multiple methods
test('it validates and creates')
    ->linksAndCovers(UserService::class.'::validate')
    ->linksAndCovers(UserService::class.'::create');

PHPUnit

// tests/Unit/UserServiceTest.php
use TestFlowLabs\TestingAttributes\LinksAndCovers;
use TestFlowLabs\TestingAttributes\Links;

class UserServiceTest extends TestCase
{
    // Link + Coverage
    #[LinksAndCovers(UserService::class, 'create')]
    public function testItCreatesUser(): void
    {
        // ...
    }

    // Link only
    #[Links(UserService::class, 'create')]
    public function testItCreatesUserIntegration(): void
    {
        // ...
    }

    // Multiple methods
    #[LinksAndCovers(UserService::class, 'validate')]
    #[LinksAndCovers(UserService::class, 'create')]
    public function testItValidatesAndCreates(): void
    {
        // ...
    }
}

CLI Commands

# Show coverage links report
testlink report

# Validate bidirectional sync
testlink validate

# Auto-sync from #[TestedBy] to test files
testlink sync

# Preview sync changes (dry run)
testlink sync --dry-run

# Sync and prune orphaned links
testlink sync --prune --force

# Export as JSON
testlink report --json

# Show help
testlink --help
testlink sync --help

Sample Output

  Coverage Links Report
  ─────────────────────

  App\Services\UserService

    create()
      → Tests\Unit\UserServiceTest::it creates a user
      → Tests\Unit\UserServiceTest::it validates email format

    update()
      → Tests\Unit\UserServiceTest::it updates a user

  Summary
    Methods with tests: 2
    Total test links: 3

Validation

The validate command checks for:

• Missing Coverage: Production methods with #[TestedBy] but no matching link call
• Orphaned Links: Tests claiming links that don't exist
• Sync Issues: Mismatched bidirectional links

$ testlink validate

  Validation Report
  ─────────────────

  Missing Link Calls in Tests
  These #[TestedBy] attributes have no corresponding link calls:

    ✗ App\Services\OrderService::process
      → Tests\Unit\OrderServiceTest::it processes order

  Orphaned Link Calls in Tests
  These link calls have no corresponding #[TestedBy] attributes:

    ! Tests\Unit\PaymentTest::it charges card
      → App\Services\PaymentService::charge

  Validation failed. Run "testlink sync" to fix issues.

Auto-Sync

Automatically generate link calls from #[TestedBy] attributes:

# Preview what will change
testlink sync --dry-run

# Apply sync
testlink sync

# Sync and remove orphaned links
testlink sync --prune --force

How It Works

1. Scans production code for #[TestedBy] attributes
2. Locates corresponding test files and test cases
3. Adds missing linksAndCovers() calls (Pest) or #[LinksAndCovers] attributes (PHPUnit)

Before Sync (Pest)

// Production code has the attribute
#[TestedBy(UserServiceTest::class, 'it creates a user')]
public function create(): User { }

// Test file is missing link
test('it creates a user', function () { });

After Sync (Pest)

test('it creates a user', function () {
    // ...
})->linksAndCovers(UserService::class.'::create');

Before Sync (PHPUnit)

// Production code has the attribute
#[TestedBy(UserServiceTest::class, 'testItCreatesUser')]
public function create(): User { }

// Test file is missing attribute
public function testItCreatesUser(): void { }

After Sync (PHPUnit)

#[LinksAndCovers(UserService::class, 'create')]
public function testItCreatesUser(): void { }

Link Types

Use Link + Coverage for unit tests where you want coverage tracking. Use Link Only for integration/e2e tests where unit coverage is already tracked elsewhere.

JSON Export

For CI/CD integration:

testlink report --json > coverage-links.json

{
  "links": {
    "App\\Services\\UserService::create": [
      "Tests\\Unit\\UserServiceTest::it creates a user"
    ]
  },
  "summary": {
    "total_methods": 1,
    "total_tests": 1
  }
}

Bootstrap (Pest)

Add to tests/Pest.php to enable linksAndCovers() and links() methods:

use TestFlowLabs\TestLink\Runtime\RuntimeBootstrap;

RuntimeBootstrap::init();

Best Practices

1. Prefer #[TestedBy] Attributes

Placing links in production code keeps coverage visible where it matters:

#[TestedBy(UserServiceTest::class, 'it creates a user')]
public function create(): User
{
    // Reader immediately knows this method is tested
}

2. Use Link Types Appropriately

// Unit test - use linksAndCovers for coverage
test('it creates a user with valid data')
    ->linksAndCovers(UserService::class.'::create');

// Integration test - use links for traceability only
test('it creates user through API endpoint')
    ->links(UserService::class.'::create');

3. Run Validation in CI

# .github/workflows/test.yml
- name: Validate coverage links
  run: testlink validate --strict

Hybrid Projects

TestLink seamlessly supports projects using both Pest and PHPUnit:

$ testlink report

  Coverage Links Report
  ─────────────────────

  Detected frameworks: pest, phpunit

  App\Services\UserService
    create()
      → Tests\Unit\UserServiceTest::it creates a user (pest)
      → Tests\Integration\UserApiTest::testCreateUser (phpunit)

Documentation

Full documentation is available at the TestLink Documentation.

• Tutorials - Learn TestLink step-by-step with TDD and BDD workflows
• How-to Guides - Solve specific problems and tasks
• Reference - CLI commands, attributes, and configuration
• Explanation - Understand bidirectional linking concepts

Ecosystem

TestLink is part of the TestFlowLabs ecosystem:

Contributing

1. Fork the repository
2. Create a feature branch
3. Run composer test to ensure all checks pass
4. Submit a pull request

License

MIT License. See LICENSE for details.