Add sample tests to show example of test-driven documentation workflow

Author: ajcastro

app/Http/Controllers/SideProjectController.php

@@ -68,7 +68,7 @@ public function store(Request $request)
      * @transformer  App\Http\Transformers\SideProjectTransformer
      * @transformerModel App\Models\SideProject with=owner
      */
-    public function show(SideProject $id)
+    public function show(SideProject $sideProject)
     {
         $fractal = new Manager();
         $resource = new Item($sideProject, new SideProjectTransformer());

app/Http/Controllers/UserController.php

@@ -37,7 +37,7 @@ public function store(CreateUserRequest $request)
         /** @var User $user */
         $user = User::create($request->validated());
         $token = $user->createToken('default');
-        return ['user' => $user, 'token' => $token->plainTextToken];
+        return response(['user' => $user, 'token' => $token->plainTextToken], 201);
     }
 
     /**

app/Models/SideProject.php

@@ -9,6 +9,13 @@ class SideProject extends Model
 {
     use HasFactory;
 
+    protected $fillable = [
+        'name',
+        'description',
+        'due_at',
+        'user_id',
+    ];
+
     public function owner()
     {
         return $this->belongsTo(User::class, 'user_id');

tests/Feature/Http/Controllers/SideProjectControllerTest.php

@@ -0,0 +1,109 @@
+<?php
+
+namespace Tests\Feature\Http\Controllers;
+
+use App\Models\SideProject;
+use App\Models\User;
+use Tests\TestCase;
+
+/**
+ * @group Side Projects
+ */
+class SideProjectControllerTest extends TestCase
+{
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->actingAs(User::factory()->create());
+    }
+
+    /**
+     * View all side projects
+     *
+     * This endpoint's response was gotten via a "response call"—
+     * Scribe called our API in a test environment to get a sample response.
+     */
+    public function test_side_projects_index()
+    {
+        $response = $this->get(route('side_projects.index'));
+
+        $response->assertOk();
+    }
+
+    /**
+     * Start a new side project
+     *
+     * _Even though we both know you'll never finish it._
+     *
+     * This endpoint's body parameters were automatically generated by Scribe
+     * from the controller's code. Check out the source! </aside>
+     *
+     * @authenticated
+     */
+    public function test_side_projects_store()
+    {
+        $data = SideProject::factory()->make()->toArray();
+
+        $response = $this->post(route('side_projects.store'), $data);
+
+        $response->assertCreated();
+    }
+
+    /**
+     * View a side project
+     *
+     * This endpoint's response uses a Fractal transformer, so we tell Scribe that using an annotation,
+     * and it figures out how to generate a sample. The 404 sample is gotten from a "response file".
+     *
+     * <aside class="success">Also, pretty cool: this endpoint's (and many others') URL parameters were figured out entirely by Scribe!</aside>
+     *
+     * @transformer  App\Http\Transformers\SideProjectTransformer
+     * @transformerModel App\Models\SideProject with=owner
+     */
+    public function test_side_projects_show()
+    {
+        $user = SideProject::factory()->create();
+
+        $response = $this->get(route('side_projects.show', $user));
+
+        $response->assertOk();
+    }
+
+    /**
+     * Update a side project
+     *
+     */
+    public function test_side_projects_update()
+    {
+        $user = SideProject::factory()->create();
+        $data = SideProject::factory()->make()->toArray();
+
+        $response = $this->put(route('side_projects.update', $user), $data);
+
+        $response->assertOk();
+    }
+
+    /**
+     * Delete a side project
+     *
+     */
+    public function test_side_projects_destroy()
+    {
+        $user = SideProject::factory()->create();
+
+        $response = $this->put(route('side_projects.destroy', $user));
+
+        $response->assertOk();
+    }
+
+    /**
+     * Finish a side project
+     *
+     * Hmmm.🤔
+     */
+    public function test_side_projects_finish()
+    {
+        //
+    }
+}

tests/Feature/Http/Controllers/UserControllerTest.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Tests\Feature\Http\Controllers;
+
+use App\Models\User;
+use Tests\TestCase;
+
+/**
+ * @group Users
+ */
+class UserControllerTest extends TestCase
+{
+    /**
+     * View all users
+     *
+     * This endpoint uses a custom Scribe strategy that parses a
+     * `@usesPagination` annotation to add some query parameters.
+     *
+     * The sample response is gotten by Scribe making a test API call (aka "response call").
+     *
+     * @usesPagination
+     */
+    public function test_users_index()
+    {
+        $response = $this->get('api/users');
+
+        $response->assertOk();
+    }
+
+    /**
+     * Create a user
+     *
+     * This endpoint's body parameters are automatically generated from a FormRequest.
+     */
+    public function test_users_store()
+    {
+        $data = User::factory()->make()->toArray()+['password' => 'as123as35y'];
+
+        $response = $this->post('api/users', $data);
+
+        $response
+        ->assertCreated();
+    }
+
+    /**
+     * Authenticate
+     *
+     * Get a new API token.
+     *
+     * <aside>Yes, we know you can impersonate any user.🙄</aside>
+     *
+     * @response {"token": "2|KLDoUXc68Ko0JaFDZoX9qYkUqWglwdGxQsvTGBCg"}
+     * @responseField token The new API token. Valid forever.
+     */
+    public function test_users_authenticate()
+    {
+        $user = User::factory()->create();
+
+        $response = $this->post("api/users/{$user->id}/auth");
+
+        $response
+        ->assertOk()
+        ->assertJsonStructure([
+            'token',
+        ]);
+    }
+
+    /**
+     * Fetch a user
+     *
+     * This endpoint's response uses an Eloquent API resource, so we tell Scribe that using an annotation,
+     * and it figures out how to generate a sample. The 404 sample is gotten from a "response file".
+     *
+     * @apiResource App\Http\Resources\UserResource
+     * @apiResourceModel App\Models\User with=sideProjects
+     * @responseFile 404 scenario="User not found" responses/not_found.json {"resource": "user"}
+     */
+    public function test_users_show()
+    {
+        $user = User::factory()->create();
+
+        $response = $this->get("api/users/{$user->id}");
+
+        $response
+        ->assertOk();
+    }
+
+    /**
+     * Update the specified resource in storage.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @param  int  $id
+     * @return \Illuminate\Http\Response
+     */
+    public function test_users_update()
+    {
+        //
+    }
+
+    /**
+     * Remove the specified resource from storage.
+     *
+     * @param  int  $id
+     * @return \Illuminate\Http\Response
+     */
+    public function test_users_destroy()
+    {
+        //
+    }
+}