PHPackages                             samasend/scribe-tdd - 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. samasend/scribe-tdd

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

samasend/scribe-tdd
===================

Scribe's test-driven documentation approach.

0242PHP

Since Jun 23Pushed 2y agoCompare

[ Source](https://github.com/SamAsEnd/scribe-tdd)[ Packagist](https://packagist.org/packages/samasend/scribe-tdd)[ RSS](/packages/samasend-scribe-tdd/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Scribe TDD (Test-driven Documentation)
======================================

[](#scribe-tdd-test-driven-documentation)

[Scribe](https://github.com/knuckleswtf/scribe)'s test-driven documentation approach.

Benefits
========

[](#benefits)

- Better workflow, instead of writing docblock annotations for parameters in controller, you can auto-generate documentation from the tests performed.
- Less comments cluttering in controllers. Some annotations are still needed (like @group) but annotations can be put in the test classes instead.
- Easy to document controllers which methods are inherited from base controllers or traits by putting docblocks in the test methods.
- Follows the principle "If it is not tested, it does not exist.". This makes sure your docs and tests are in sync.
- It is easy to document responses because it is from the performed tests and does not rely on response calls which sometimes result to errors due to inconsistent database state.

Installation and Setup
----------------------

[](#installation-and-setup)

### Step 1: Composer Require

[](#step-1-composer-require)

```
composer require --dev ajcastro/scribe-tdd

```

### Step 2: Use ScribeTddSetup trait in TestCase

[](#step-2-use-scribetddsetup-trait-in-testcase)

```
use AjCastro\ScribeTdd\Tests\ScribeTddSetup;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication, ScribeTddSetup;

    public function setUp(): void
    {
        parent::setUp();

        $this->setUpScribeTdd();
    }
}
```

### Step 3: Set the necessary strategies

[](#step-3-set-the-necessary-strategies)

```
    'strategies' => [
        'metadata' => [
            // ...
            AjCastro\ScribeTdd\Strategies\Metadata\GetFromDocBlocksFromScribeTdd::class,
        ],
        'urlParameters' => [
            // ...
            AjCastro\ScribeTdd\Strategies\UrlParameters\GetFromUrlParamTagFromScribeTdd::class,
        ],
        'queryParameters' => [
            // ...
            AjCastro\ScribeTdd\Strategies\QueryParameters\GetFromTestResult::class,
            AjCastro\ScribeTdd\Strategies\QueryParameters\AddPaginationParametersFromScribeTdd::class,
            AjCastro\ScribeTdd\Strategies\QueryParameters\GetFromQueryParamTagFromScribeTdd::class,
        ],
        'headers' => [
            // ...
            AjCastro\ScribeTdd\Strategies\Headers\GetFromHeaderTagFromScribeTdd::class,
        ],
        'bodyParameters' => [
            // ...
            AjCastro\ScribeTdd\Strategies\BodyParameters\GetFromTestResult::class,
            AjCastro\ScribeTdd\Strategies\BodyParameters\GetFromBodyParamTagFromScribeTdd::class,
        ],
        'responses' => [
            // ...
            AjCastro\ScribeTdd\Strategies\Responses\GetFromTestResult::class,
            AjCastro\ScribeTdd\Strategies\Responses\UseResponseTagFromScribeTdd::class,
            AjCastro\ScribeTdd\Strategies\Responses\UseResponseFileTagFromScribeTdd::class,
        ],
        'responseFields' => [
            // ...
            AjCastro\ScribeTdd\Strategies\ResponseFields\GetFromResponseFieldTagFromScribeTdd::class,
        ],
    ],
```

It is up to you if you want to disable existing default strategies or just add these strategies so you can enjoy both worlds.

Usage
-----

[](#usage)

### Step 1: Create and run tests

[](#step-1-create-and-run-tests)

Just create your usual phpunit tests and run them. This will generate the necessary files that will be used for generating scribe documentation later.

```
phpunit

```

### Step 2: Run scribe:generate

[](#step-2-run-scribegenerate)

Make sure to use `--force` to remove cached output.

```
php artisan scribe:generate --force

```

### Step 3: Gitignore auto-generated json files

[](#step-3-gitignore-auto-generated-json-files)

Add the following to your `.gitignore` to ignore auto-generated json files. You should commit your created files, those which are ending in `-@.json`, so that it will always be applied when generating api documentation.

```
storage/scribe-tdd/*/*
!storage/scribe-tdd/*/*-@.json

```

### Step 4: Delete auto-generated files (Optional)

[](#step-4-delete-auto-generated-files-optional)

When you run the `phpunit` tests, it creates a lot of files. You can delete these files when you already generated the api documentation by running the command below. This will not delete your created files.

```
php artisan scribe:tdd:delete

```

Sample Usage
------------

[](#sample-usage)

Here is a sample project where it uses the tdd approach: [ajcastro/TheSideProjectAPI#1](https://github.com/ajcastro/TheSideProjectAPI/pull/1)

Acknowledgement
---------------

[](#acknowledgement)

This package is inspired from [Enlighten](https://github.com/stydeNet/enlighten/).

###  Health Score

17

—

LowBetter than 6% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity22

Early-stage or recently created project

 Bus Factor1

Top contributor holds 90% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/8fd28cb32a4cca3aaf21187959977a78066f4bc4c8b110c959efcf117e6dc4c4?d=identicon)[SamAsEnd](/maintainers/SamAsEnd)

---

Top Contributors

[![ajcastro](https://avatars.githubusercontent.com/u/4918318?v=4)](https://github.com/ajcastro "ajcastro (54 commits)")[![joelvh](https://avatars.githubusercontent.com/u/129096?v=4)](https://github.com/joelvh "joelvh (3 commits)")[![SamAsEnd](https://avatars.githubusercontent.com/u/9657132?v=4)](https://github.com/SamAsEnd "SamAsEnd (2 commits)")[![keatliang2005](https://avatars.githubusercontent.com/u/473990?v=4)](https://github.com/keatliang2005 "keatliang2005 (1 commits)")

### Embed Badge

![Health badge](/badges/samasend-scribe-tdd/health.svg)

```
[![Health](https://phpackages.com/badges/samasend-scribe-tdd/health.svg)](https://phpackages.com/packages/samasend-scribe-tdd)
```

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[vimeo/psalm

A static analysis tool for finding errors in PHP applications

5.8k77.5M6.7k](/packages/vimeo-psalm)[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert

Thin assertion library for input validation in business models.

2.4k96.9M570](/packages/beberlei-assert)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)

PHPackages © 2026

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