robsontenorio/laravel-tdd-docs

TDD living docs for Laravel. Generate docs from comments at your phpunit tests.

WIP

• This is a very first trying, so code can be improved. You can help :)
• Improving english translations.

Laravel TDD docs

TDD living docs for Laravel. Generate docs from comments at your phpunit tests. Make your tests as usual and include only the comments you need to generate the reports., _(*1)

Develop your software using TDD with clean workflow and get a bonus with zero effort: living docs., _(*2)

Background

TDD is a great way to develop software. The development workflow is clean and fluid. And, if you use the BDD approach (Given, When, Then) to do it you have a good code readability, what give us a opportunity to documentate it very easely., _(*3)

As we know BEHAT uses BDD approach to write its tests (Given, When, Then). This is a great way to understand what happens to the software., _(*4)

Feature: Listing command
  In order to change the structure of the folder I am currently in
  As a UNIX user
  I need to be able see the currently available files and folders there

  Scenario: Listing two files in a directory
    Given I am in a directory "test"
    And I have a file named "foo"
    And I have a file named "bar"
    When I run "ls"
    Then I should get: "bar"

  [...] another scenarios from this same feature [...]

To use BEHAT with Laravel you need a series of settings, have some extra files, and follow a restricted pattern. The way test classes are generated is somewhat confusing, as your app grows., _(*5)

With BEHAT you can also get a detailed report of your tests when using plugins to export results to html, what is great!, _(*6)

Well, and if ... :bulb: :bulb: :bulb:

And if we could to have same result (structured tests and reports) with zero config, only using Laravel Testing Suite, simply commenting your test files?, _(*7)

Well, we develop our software using TDD with clean workflow and get a bonus with almost zero effort: living docs., _(*8)

That is, make your tests as usual and include only the comments you need to generate the reports., _(*9)

Install

Require

composer require robsontenorio/laravel-tdd-docs

Modify

Add this on phpunit.xml, _(*10)

<logging>
    <log type="testdox-xml" target="storage/app/testing-docs/report.xml"/>
</logging>

Permissions

Make sure you have permissions to write on storage/app folder., _(*11)

Run

• Run phpunit on project root
• Browse to /testing-docs route to see docs.

Example

Input

<?php

namespace Tests\Feature;

use Tests\TestCase;

/**
 * 
 * @feature Manage my threads
 * @tag threads
 * 
 * In order to manage my threads 
 * As a regular user from forum
 * I need to have control about my posted threads
 * 
 */
class ThreadTest extends TestCase
{
    public function test_An_authenticated_user_can_create_a_thread()
    {
        /** Given i am a authenticated user */
        $user = factory('App\User')->create();

        /** Given i filled all fields to create a thread */
        $thread = factory('App\Thread')->make();

        /** When request is processed */
        $response = $this->actingAs($user)->post('/api/threads', $thread->toArray());

        /** Then i sould see new thread created */
        $response->assertJsonFragment($thread->toArray());

    }

    public function test_An_authenticated_user_cant_delete_a_thread_from_another_user()
    {
        /** Given i am a authenticated user */
        $user1 = factory('App\User')->create();

        /** Given there is thread created by another user */
        $user2 = factory('App\User')->create();     

        // another user
        // NOTE: this kind of comment is not parsed
        $thread = factory('App\Thread')->create(['user_id' => $user2->id]);

        /** When request is processed */
        $response = $this->actingAs($user1)->delete("/api/threads/{$thread->id}");

        /** Then i sould a error message */
        $response->assertJsonFragment(['error' => 'You can not delete a thread from another user.']);

        /** And response status code is 403 */

        // Lets simulate a error in here, we got 200 but 403 was expected
        // NOTE: this kind of comment is not parsed
        $response->assertStatus(403);
    }
}

Output

, _(*12)

How it works

1) It read all test files from tests/Feature folder, _(*13)

2) It searchs for a full doc block on class section (feature description), _(*14)

3) It search for inline comments (steps) on each method (scenarios)., _(*15)

4) It compares phpunit output generated on storage/app/testing-docs/report.html with your test files to highlight the report with failed tests., _(*16)

5) You can see full report/docs at browsing to /testing-docs route., _(*17)

Assumptions

General

• Each file on tests/Feature folder is a feature, _(*18)

• Each class method is a scenario., _(*19)

DocBlock

• The class must have a full DocBlock comment, _(*20)

  • it must have a @feature anotation
  • it must have a @tag anotation
  • it must have a description body

• Each class method must have a test_ prefix, _(*21)

  • The inline comments inside methods must be in this format /** comment in here */

Inspiration

• Behat
• Behat html formatter plugin

TODO

• Improve regex, to avoid exceptions when docblocks does not follow pattern proposed.
• Filter by tag
• Graphs