grazulex/laravel-tddraft

A powerful Laravel package that provides LaravelTddraft functionality with modern PHP 8.3+ features.
13 3
laravel testing tdd pest laravel12 clean-code php8.3 test-driven-development draft-tests exploratory-testing red-green-refactor
Install
composer require grazulex/laravel-tddraft
Latest Version:v1.2.0
PHP:^8.3
Maintainer: Grazulex

Laravel TDDraft

Laravel TDDraft

A Laravel package that enables safe Test-Driven Development with isolated draft testing, unique reference tracking, and powerful filtering options for professional TDD workflows.

Latest Version Total Downloads License PHP Version Laravel Version Tests Code Style

📖 Table of Contents

Overview

Laravel TDDraft enables true Test-Driven Development in Laravel applications by providing a separate, isolated testing environment where you can practice the Red-Green-Refactor cycle without affecting your CI pipeline or breaking team builds.

The key innovation is the five-command workflow that separates experimental draft tests from production tests, with powerful filtering and status tracking to manage your TDD process professionally.

🏗️ Test Architecture & Isolation

Laravel TDDraft creates a completely separate testing environment that doesn't interfere with your existing test suite:

tests/
├── Feature/           # 🟢 Your production CI tests (unchanged)
├── Unit/             # 🟢 Your production CI tests (unchanged)  
└── TDDraft/          # 🔵 Isolated draft tests (new - never affects CI)
    ├── Feature/      # Draft feature tests
    ├── Unit/         # Draft unit tests
    └── .status.json  # Status tracking (auto-generated)

Key Architectural Benefits:

  • 🚫 Zero CI Interference: TDDraft tests in tests/TDDraft/ are completely excluded from your main test suites
  • 🔄 Independent Operation: Your existing tests/Unit/ and tests/Feature/ continue working exactly as before
  • 📋 Separate Test Suites: PHPUnit/Pest configuration keeps TDDraft isolated via test suite definitions
  • ⚡ Parallel Development: Teams can practice TDD in the draft environment while CI runs production tests

How Isolation Works:

Standard PHPUnit/Pest Configuration:

<testsuites>
    <testsuite name="Unit">
        <directory suffix="Test.php">tests/Unit</directory>      <!-- Production tests -->
    </testsuite>
    <testsuite name="Feature">
        <directory suffix="Test.php">tests/Feature</directory>   <!-- Production tests -->
    </testsuite>
    <!-- tests/TDDraft/ is intentionally NOT included -->
</testsuites>

TDDraft Tests Run Separately:

# Your CI pipeline (unchanged)
pest                          # Runs only tests/Unit + tests/Feature
phpunit                       # Runs only tests/Unit + tests/Feature

# TDDraft workflow (isolated)
php artisan tdd:test         # Runs only tests/TDDraft/**
pest --testsuite=tddraft     # Alternative access to draft tests

This architectural separation ensures that failing TDDraft tests never break your CI builds while you practice the Red-Green-Refactor cycle.

🎯 Why Laravel TDDraft?

TDD is hard to practice in real projects because:

  • Writing failing tests breaks CI builds and affects the team
  • Experimental tests clutter your main test suite
  • There's no easy way to track test evolution during TDD cycles
  • Promoting draft tests to production requires manual work

Laravel TDDraft solves these problems with:

  • ✅ Isolated Draft Testing - Separate test environment that never affects CI
  • ✅ Unique Reference Tracking - Every test gets a trackable ID for evolution monitoring
  • ✅ Powerful Filtering - Advanced options to filter tests by type, path, status, and reference
  • ✅ Status Tracking - Automatic monitoring of test results and history
  • ✅ Automated Promotion - Easy graduation from draft to production tests
  • ✅ Professional Workflow - Structured five-command process for TDD adoption

✨ Features

  • 🏗️ Complete Test Isolation - tests/TDDraft/ directory completely separate from tests/Unit/ and tests/Feature/ - never affects CI
  • 🔖 Unique Reference Tracking - Every test gets a tdd-YYYYMMDDHHMMSS-RANDOM ID for precise tracking
  • 🔍 Advanced Filtering - Filter tests by type, path, reference, status, and more
  • 📊 Automatic Status Tracking - Monitor test results and history during TDD cycles
  • 🎯 Professional Test Management - List, filter, and manage draft tests with detailed views
  • 🚀 Automated Promotion - Graduate mature tests to CI suite with preserved audit trails
  • 🔄 True TDD Workflow - Safe Red-Green-Refactor cycles without breaking builds
  • 📋 Group-Based Organization - Pest groups for flexible test filtering and execution
  • ⚡ Five-Command Simplicity - Complete TDD workflow with just five intuitive commands
  • 🧪 Zero Interference Design - Your existing Unit/Feature tests continue working unchanged

📦 Installation

Install the package via Composer:

composer require grazulex/laravel-tddraft --dev

💡 Auto-Discovery
The service provider will be automatically registered thanks to Laravel's package auto-discovery.

Publish configuration:

php artisan vendor:publish --tag=tddraft-config

🚀 Quick Start

1. Initialize TDDraft Environment

php artisan tdd:init

This sets up the isolated draft testing environment with PHPUnit/Pest configuration.

2. Create Your First Draft Test

php artisan tdd:make "User can register"

Creates a draft test with unique reference tracking:

/**
 * TDDraft Test: User can register
 * Reference: tdd-20250727142530-Abc123
 * Type: feature
 */

it('user can register', function (): void {
    // TODO: Implement your test scenario here
    expect(true)->toBeTrue('Replace this with your actual test implementation');
})
->group('tddraft', 'feature', 'tdd-20250727142530-Abc123');

3. Run Draft Tests with Filtering

# Run all draft tests
php artisan tdd:test

# Filter by test name
php artisan tdd:test --filter="user registration"

# Run with coverage
php artisan tdd:test --coverage

4. Manage Tests with Advanced Filtering

# List all draft tests
php artisan tdd:list

# Filter by type
php artisan tdd:list --type=feature

# Filter by path
php artisan tdd:list --path=Auth

# Show detailed view with status information
php artisan tdd:list --details

5. Promote Mature Tests to CI Suite

# Find reference from listing
php artisan tdd:list

# Promote specific test
php artisan tdd:promote tdd-20250727142530-Abc123

🔧 Five-Command TDD Workflow

Laravel TDDraft is built around a structured five-command workflow that enables professional TDD practice:

1. tdd:init - Setup Phase

php artisan tdd:init
  • Creates tests/TDDraft/ directory structure
  • Configures PHPUnit/Pest for isolated draft testing
  • Sets up status tracking system

2. tdd:make - Red Phase (Create Failing Tests)

php artisan tdd:make "Feature description" [options]

Options:

  • --type=feature|unit - Specify test type (default: feature)
  • --path=Auth/Api - Custom subdirectory path
  • --class=CustomTestName - Custom class name

Creates draft test with unique tracking reference.

3. tdd:test - Green Phase (Run and Iterate)

php artisan tdd:test [options]

Options:

  • --filter="test name" - Filter tests by name pattern
  • --coverage - Generate coverage report
  • --parallel - Run tests in parallel
  • --stop-on-failure - Stop on first failure

Runs draft tests with automatic status tracking.

4. tdd:list - Review Phase (Manage Tests)

php artisan tdd:list [options]

Options:

  • --type=feature|unit - Filter by test type
  • --path=directory - Filter by directory path
  • --details - Show detailed view with status history

View and filter all draft tests with their current status.

5. tdd:promote - Graduation Phase (Move to CI)

php artisan tdd:promote <reference> [options]

Options:

  • --target=Feature|Unit - Target directory override
  • --new-file=TestName - Custom file name
  • --class=ClassName - Custom class name
  • --keep-draft - Keep original draft file
  • --force - Overwrite without confirmation

Promotes mature tests to main test suite with audit trail preservation.

🔍 Filter and Group Options

Laravel TDDraft provides powerful filtering capabilities across all commands:

Command-Specific Filters

tdd:list Command Filters

# Filter by test type
php artisan tdd:list --type=feature
php artisan tdd:list --type=unit

# Filter by directory path
php artisan tdd:list --path=Auth
php artisan tdd:list --path=Api/V1

# Show detailed view with status history
php artisan tdd:list --details

# Combine filters
php artisan tdd:list --type=feature --path=Auth --details

tdd:test Command Filters

# Filter by test name pattern
php artisan tdd:test --filter="user registration"
php artisan tdd:test --filter="login"

# Filter by specific reference
php artisan tdd:test --filter="tdd-20250727142530-Abc123"

# Run with additional options
php artisan tdd:test --filter="api" --coverage --parallel

Pest Group System

Every draft test is automatically tagged with multiple groups for flexible filtering:

it('user can register', function (): void {
    // Test implementation
})
->group('tddraft', 'feature', 'tdd-20250727142530-Abc123');

Group Types:

  • tddraft - Identifies all TDDraft tests
  • feature/unit - Test type classification
  • tdd-YYYYMMDDHHMMSS-RANDOM - Unique reference for individual test tracking

Direct Pest Filtering:

# Run only draft tests (all)
pest --testsuite=tddraft

# Run only feature draft tests
pest --testsuite=tddraft --group=feature

# Run only unit draft tests
pest --testsuite=tddraft --group=unit

# Run specific test by reference
pest --testsuite=tddraft --group=tdd-20250727142530-Abc123

# Run multiple groups
pest --testsuite=tddraft --group=feature,unit

Status-Based Management

Use the status tracking system to filter by test stability:

# List tests and check their status
php artisan tdd:list --details

# Example output shows status information:
# 📊 ✅ Passed   - Ready for promotion
# 📊 ❌ Failed   - Needs attention
# 📊 ⏭️ Skipped  - Review implementation
# 📊 🎯 Promoted - Already moved to CI

Reference-Based Operations

Each test gets a unique reference for precise operations:

# Create test (generates reference)
php artisan tdd:make "User login validation"
# Output: Reference: tdd-20250727142530-Abc123

# Run specific test by reference
php artisan tdd:test --filter="tdd-20250727142530-Abc123"

# Promote specific test
php artisan tdd:promote tdd-20250727142530-Abc123

# List to find references
php artisan tdd:list | grep "tdd-"

Advanced Filtering Examples

# Find all authentication-related tests
php artisan tdd:list --path=Auth --details

# Run only feature tests for API
php artisan tdd:test --filter="api" 
pest --testsuite=tddraft --group=feature | grep -i api

# Batch operations on specific test types
php artisan tdd:list --type=unit | grep "✅ Passed"  # Find unit tests ready for promotion

# Status tracking analysis
php artisan tdd:list --details | grep "❌ Failed"   # Find tests needing attention

📚 Documentation

For detailed documentation, examples, and advanced usage, please visit our comprehensive wiki:

🌟 Complete Documentation & Examples Wiki

Quick Links:

💡 Examples

Basic TDD Workflow

# 1. Setup (one-time)
php artisan tdd:init

# 2. Create failing test (Red phase)
php artisan tdd:make "User can register with valid email"

# 3. Run tests and implement code (Green phase)
php artisan tdd:test --filter="register"

# 4. List and manage your tests
php artisan tdd:list --details

# 5. Promote stable tests to CI
php artisan tdd:promote tdd-20250727142530-Abc123

Advanced Usage

For comprehensive examples including:

  • Real-world TDD workflows
  • Advanced filtering techniques
  • Team collaboration patterns
  • Integration with CI/CD
  • Performance optimization

👉 Visit our Examples Wiki

🧪 Testing

Laravel TDDraft follows its own philosophy - all tests are organized using the TDD workflow with complete isolation between test environments:

Test Architecture

tests/
├── Feature/           # Package's production tests (for CI)
├── Unit/             # Package's production tests (for CI)
└── TDDraft/          # Draft tests (isolated, never affects CI)

Running Tests

# Install dependencies
composer install

# Run the main CI test suite (production tests only)
pest                  # Runs tests/Unit + tests/Feature
pest --coverage       # With coverage for production tests

# Run specific production test groups
pest --group=unit     # Unit tests only
pest --group=feature  # Feature tests only

# TDDraft workflow (completely separate)
php artisan tdd:test  # Runs only tests/TDDraft/** tests
php artisan tdd:list  # Manage draft tests

Test Isolation Benefits

For Package Development:

  • Production tests (tests/Unit/, tests/Feature/) ensure package stability
  • CI pipeline only runs production tests - never broken by experimental code
  • Draft tests demonstrate package capabilities without affecting main suite

For Package Users:

  • Your existing tests/Unit/ and tests/Feature/ remain unchanged
  • TDDraft adds tests/TDDraft/ for safe TDD practice
  • No interference between production and draft test environments

Writing Tests for This Package

If you're contributing to Laravel TDDraft itself, follow the same TDD principles:

  1. Write failing tests first
  2. Implement minimal code to make them pass
  3. Refactor while keeping tests green

The package tests itself using the standard Laravel/Pest approach, while providing TDDraft workflow for users.

🔧 Requirements

  • PHP: ^8.3
  • Laravel: ^12.0
  • Pest: ^3.0 (for testing framework)

Optional Dependencies

  • PHPUnit: ^11.0 (alternative to Pest)
  • Docker: For containerized development (optional)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🔒 Security

If you discover a security vulnerability, please review our Security Policy before disclosing it.

📄 License

Laravel TDDraft is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community

Resources

Community Links