PHPackages                             grazulex/laravel-tddraft - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. grazulex/laravel-tddraft

ActiveLibrary[Testing & Quality](/categories/testing)

grazulex/laravel-tddraft
========================

A powerful Laravel package that provides LaravelTddraft functionality with modern PHP 8.3+ features.

v1.2.0(9mo ago)413[1 issues](https://github.com/Grazulex/laravel-tddraft/issues)MITPHPPHP ^8.3CI passing

Since Jul 20Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/Grazulex/laravel-tddraft)[ Packagist](https://packagist.org/packages/grazulex/laravel-tddraft)[ Docs](https://github.com/grazulex/laravel-tddraft)[ RSS](/packages/grazulex-laravel-tddraft/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (10)Versions (3)Used By (0)

Laravel TDDraft
===============

[](#laravel-tddraft)

[![Laravel TDDraft](new_logo.png)](new_logo.png)

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](https://camo.githubusercontent.com/0455f60fc3cec5649935308990508f475a9880978b749d7242b67087246b98a1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6772617a756c65782f6c61726176656c2d746464726166742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/grazulex/laravel-tddraft)[![Total Downloads](https://camo.githubusercontent.com/ceaf9e961e85cc74b4771fa1eb501a4dab41e1e2c7ed581faa78b97617bb8f42/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6772617a756c65782f6c61726176656c2d746464726166742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/grazulex/laravel-tddraft)[![License](https://camo.githubusercontent.com/5de80b72d5e8db31a2fd09d82e8e7edc57e25644a6cdf1f828f71cae6e1d9e2e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6772617a756c65782f6c61726176656c2d746464726166742e7376673f7374796c653d666c61742d737175617265)](https://github.com/Grazulex/laravel-tddraft/blob/main/LICENSE.md)[![PHP Version](https://camo.githubusercontent.com/c4cd3aa93432c5306158a55070bfe22da0b419c3e4e1255763e90e7fa124df80/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6772617a756c65782f6c61726176656c2d746464726166742e7376673f7374796c653d666c61742d737175617265)](https://php.net/)[![Laravel Version](https://camo.githubusercontent.com/7592d340e2de1142fa869382b819654d6a0bf7baf8e3c8aded777d652d68c01a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31322e782d6666326432303f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c)](https://laravel.com/)[![Tests](https://camo.githubusercontent.com/d177ac727b860fa863ca348256f545726636781fc64cb16f823750ce71830ad3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6772617a756c65782f6c61726176656c2d746464726166742f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/Grazulex/laravel-tddraft/actions)[![Code Style](https://camo.githubusercontent.com/161d70e6871f808e0439b3e7a86540993ae98775540b5a2e78226000e3c419c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64652532307374796c652d70696e742d3030303030303f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c)](https://github.com/laravel/pint)

📖 Table of Contents
-------------------

[](#-table-of-contents)

- [Overview](#overview)
- [✨ Features](#-features)
- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [🔧 Five-Command TDD Workflow](#-five-command-tdd-workflow)
- [🔍 Filter and Group Options](#-filter-and-group-options)
- [📚 Documentation](#-documentation)
- [💡 Examples](#-examples)
- [🧪 Testing](#-testing)
- [🔧 Requirements](#-requirements)
- [🤝 Contributing](#-contributing)
- [🔒 Security](#-security)
- [📄 License](#-license)

Overview
--------

[](#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
------------------------------------

[](#️-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:

[](#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:

[](#how-isolation-works)

**Standard PHPUnit/Pest Configuration:**

```

        tests/Unit

        tests/Feature

```

**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?

[](#-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
----------

[](#-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
--------------

[](#-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
-------------

[](#-quick-start)

### 1. Initialize TDDraft Environment

[](#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

[](#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

[](#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

[](#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

[](#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
---------------------------

[](#-five-command-tdd-workflow)

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

### 1. `tdd:init` - Setup Phase

[](#1-tddinit---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)

[](#2-tddmake---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)

[](#3-tddtest---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)

[](#4-tddlist---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)

[](#5-tddpromote---graduation-phase-move-to-ci)

```
php artisan tdd:promote  [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
--------------------------

[](#-filter-and-group-options)

Laravel TDDraft provides powerful filtering capabilities across all commands:

### Command-Specific Filters

[](#command-specific-filters)

#### `tdd:list` Command Filters

[](#tddlist-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

[](#tddtest-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

[](#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:

[](#group-types)

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

#### Direct Pest Filtering:

[](#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

[](#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

[](#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

[](#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
---------------

[](#-documentation)

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

**🌟 [Complete Documentation & Examples Wiki](https://github.com/Grazulex/laravel-tddraft/wiki)**

### Quick Links:

[](#quick-links)

- � [Full Documentation](https://github.com/Grazulex/laravel-tddraft/wiki)
- 🚀 [Quick Start Guide](https://github.com/Grazulex/laravel-tddraft/wiki/Quick-Start)
- 🔧 [Configuration](https://github.com/Grazulex/laravel-tddraft/wiki/Configuration)
- 💡 [Advanced Examples](https://github.com/Grazulex/laravel-tddraft/wiki/Examples)
- 🎯 [Best Practices](https://github.com/Grazulex/laravel-tddraft/wiki/Best-Practices)
- 🧪 [Test Templates](https://github.com/Grazulex/laravel-tddraft/wiki/Templates)
- 📊 [Coverage & Reporting](https://github.com/Grazulex/laravel-tddraft/wiki/Coverage)

💡 Examples
----------

[](#-examples)

### Basic TDD Workflow

[](#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

[](#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](https://github.com/Grazulex/laravel-tddraft/wiki/Examples)**

🧪 Testing
---------

[](#-testing)

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

### Test Architecture

[](#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

[](#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

[](#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

[](#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
--------------

[](#-requirements)

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

### Optional Dependencies

[](#optional-dependencies)

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

🤝 Contributing
--------------

[](#-contributing)

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

🔒 Security
----------

[](#-security)

If you discover a security vulnerability, please review our [Security Policy](SECURITY.md) before disclosing it.

📄 License
---------

[](#-license)

Laravel TDDraft is open-sourced software licensed under the [MIT license](LICENSE.md).

---

**Made with ❤️ for the Laravel community**

### Resources

[](#resources)

- [📖 Documentation Wiki](https://github.com/Grazulex/laravel-tddraft/wiki)
- [💬 Discussions](https://github.com/Grazulex/laravel-tddraft/discussions)
- [🐛 Issue Tracker](https://github.com/Grazulex/laravel-tddraft/issues)
- [📦 Packagist](https://packagist.org/packages/grazulex/laravel-tddraft)

### Community Links

[](#community-links)

- [CODE\_OF\_CONDUCT.md](CODE_OF_CONDUCT.md) - Our code of conduct
- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute
- [SECURITY.md](SECURITY.md) - Security policy
- [RELEASES.md](RELEASES.md) - Release notes and changelog

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance52

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 58.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Total

2

Last Release

290d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/888105bd54b6b7f7905523a16a1d08eebc2e5d39b19a4c174b5961bb4d52929b?d=identicon)[Grazulex](/maintainers/Grazulex)

---

Top Contributors

[![Grazulex](https://avatars.githubusercontent.com/u/4521546?v=4)](https://github.com/Grazulex "Grazulex (44 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (31 commits)")

---

Tags

laravelpackagepestphptestingtestingpestlaravelTDDclean codelaravel12php8.3test-driven-developmentdraft-testsexploratory-testingred-green-refactor

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/grazulex-laravel-tddraft/health.svg)

```
[![Health](https://phpackages.com/badges/grazulex-laravel-tddraft/health.svg)](https://phpackages.com/packages/grazulex-laravel-tddraft)
```

###  Alternatives

[timacdonald/log-fake

A drop in fake logger for testing with the Laravel framework.

4235.9M56](/packages/timacdonald-log-fake)[defstudio/pest-plugin-laravel-expectations

A plugin to add laravel tailored expectations to Pest

98548.9k4](/packages/defstudio-pest-plugin-laravel-expectations)[srlabs/laravel-testing-utilities

Helper utilities for testing Laravel Applications

1011.9k](/packages/srlabs-laravel-testing-utilities)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)