# Testing with PHPUnit

Lighthouse makes it easy to add automated tests through PHPUnit (opens new window).

# Setup

Lighthouse offers some useful test helpers. Keep in mind they only work when your test class extends Illuminate\Foundation\Testing\TestCase.

The MakesGraphQLRequests trait make it easy to call your API:

+use Nuwave\Lighthouse\Testing\MakesGraphQLRequests;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;
+   use MakesGraphQLRequests;
}

Enabling the schema cache speeds up your tests. To ensure the schema is fresh before running tests, add the RefreshesSchemaCache trait:

+use Nuwave\Lighthouse\Testing\RefreshesSchemaCache;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;
+   use RefreshesSchemaCache;
}

If you want to test subscriptions, add the TestsSubscriptions trait:

+use Nuwave\Lighthouse\Testing\TestsSubscriptions;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;
+   use TestsSubscriptions;
}

# Running Queries

The most natural way of testing your GraphQL API is to run actual GraphQL queries.

The graphQL test helper runs a query on your GraphQL endpoint and returns a TestResponse.

public function testQueriesPosts(): void
{
    $response = $this->graphQL(/** @lang GraphQL */ '
    {
        posts {
            id
            title
        }
    }
    ');
}

If you want to use variables within your query, pass an associative array as the second argument:

public function testCreatePost(): void
{
    $response = $this->graphQL(/** @lang GraphQL */ '
        mutation ($title: String!) {
            createPost(title: $title) {
                id
            }
        }
    ', [
        'title' => 'Automatic testing proven to reduce stress levels in developers'
    ]);
}

You can run a subscription query the same way.

public function testPostsSubscription(): void
{
    $response = $this->graphQL(/** @lang GraphQL */ '
    {
        subscription {
            onPostCreated {
                title
            }
        }
    }
    ');
}

# Assertions

Now that we know how to query our server in tests, we need to make sure the returned results match our expectations.

The returned TestResponse conveniently offers assertions that work quite well with the JSON data returned by GraphQL.

The assertJson method asserts that the response is a superset of the given JSON.

public function testQueriesPosts(): void
{
    $post = factory(Post::class)->create();

    $this->graphQL(/** @lang GraphQL */ '
    {
        posts {
            id
            title
        }
    }
    ')->assertJson([
        'data' => [
            'posts' => [
                [
                    'id' => $post->id,
                    'title' => $post->title,
                ],
            ],
        ],
    ]);
}

You can also extract data from the response and use it within any assertion.

public function testOrdersUsersByName(): void
{
    factory(User::class)->create(['name' => 'Oliver']);
    factory(User::class)->create(['name' => 'Chris']);
    factory(User::class)->create(['name' => 'Benedikt']);

    $response = $this->graphQL(/** @lang GraphQL */ '
    {
        users(orderBy: "name") {
            name
        }
    }
    ');

    $names = $response->json("data.*.name");

    $this->assertSame(
        [
            'Benedikt',
            'Chris',
            'Oliver',
        ],
        $names
    );
}

# Subscription Assertions

# Testing Authorization

Once you do your subscription query and get a TestResponse $response, you can run the following assertions on it.

If you want to make sure the current user is authorized to join a subscription:

$response->assertGraphQLSubscriptionAuthorized($this);

If you want to make sure the current user is NOT authorized to join a subscription:

$response->assertGraphQLSubscriptionNotAuthorized($this);

# Testing Broadcast

Once you do your subscription query and get a TestResponse $response, you can run the following assertions on it.

To assert the subscription actually received some broadcasts:

// any other way to broadcast would also work
Subscription::broadcast('postUpdated', ['title' => 'foo']);
Subscription::broadcast('postUpdated', ['title' => 'bar']);

$response->assertGraphQLBroadcasted([
    ['title' => 'foo'],
    ['title' => 'bar'],
]);

To assert the subscription received no broadcasts:

// nothing that causes a broadcast to this channel

$response->assertGraphQLNotBroadcasted();

If you need more control over your broadcast assertion you can use graphQLSubscriptionMock which returns a spy (opens new window) and graphQLSubscriptionChannelName

$spy = $response->graphQLSubscriptionMock($this);

$spy->shouldNotHaveReceived('broadcast');
// or
$spy->shouldNotHaveReceived('broadcast', function (Subscriber $subscriber, $broadcastedData) use ($response): bool {
    $channel = $response->graphQLSubscriptionChannelName();
    return $channel !== $subscriber->channel;
});

# TestResponse Assertion Mixins

Lighthouse conveniently provides additional assertions as mixins to the TestResponse class. Make sure to generate the latest IDE-helper file to get proper autocompletion:

php artisan lighthouse:ide-helper

The provided assertions are prefixed with assertGraphQL for easy discovery. They offer useful shortcuts to common testing tasks. For example, you might want to ensure that validation works properly:

$this
    ->graphQL(/** @lang GraphQL */ '
    mutation {
        createUser(email: "invalid email")
    }
    ')
    ->assertGraphQLValidationKeys(['email']);

# Testing Errors

Depending on your debug and error handling configuration, Lighthouse catches most if not all errors produced within queries and includes them within the result.

One way to test for errors is to examine the TestResponse, either by looking at the JSON response manually or by using the provided assertion mixins such as assertGraphQLErrorMessage():

$this
    ->graphQL(/** @lang GraphQL */ '
    mutation {
        shouldTriggerSomeError
    }
    ')
    ->assertGraphQLErrorMessage($expectedMessage);

Another way is to leverage PHPUnit's built-in methods such as expectException(). You must disable Lighthouse's error handling with rethrowGraphQLErrors() to ensure errors reach your test:

$this->rethrowGraphQLErrors();

$this->expectException(SomethingWentWrongException::class);
$this->graphQL(/** @lang GraphQL */ '
{
    oops
}
');

# Simulating File Uploads

Lighthouse allows you to upload files through GraphQL.

Since multipart form requests are tricky to construct, you can just use the multipartGraphQL helper method.

$operations = [
    'query' => /** @lang GraphQL */ '
        mutation ($file: Upload!) {
            upload(file: $file)
        }
    ',
    'variables' => [
        'file' => null,
    ],
];

$map = [
    '0' => ['variables.file'],
];

$file = [
    '0' => UploadedFile::fake()->create('test.pdf', 500),
];

$this->multipartGraphQL($operations, $map, $file);

# Introspection

If you create or manipulate parts of your schema programmatically, you might want to test that. You can use introspection to query your final schema in tests.

Lighthouse uses the introspection query from \GraphQL\Type\Introspection::getIntrospectionQuery() (opens new window).

The introspect() helper method runs the full introspection query against your schema.

$introspectionResult = $this->introspect();

Most often, you will want to look for a specific named type.

$generatedType = $this->introspectType('Generated');
// Ensure the type is present and matches a certain definition
$this->assertSame(
    [], // Adjust accordingly
    $generatedType
);

You can also introspect client directives.

$customDirective = $this->introspectDirective('custom');

# Defer

When sending requests with field containing @defer, use the streamGraphQL() helper. It automatically captures the full streamed response and provides you the returned chunks.

$chunks = $this->streamGraphQL(/** @lang GraphQL */ '
{
    now
    later @defer
}
');

$this->assertSame(
    [
        [
            'data' => [
                'now' => 'some value',
                'later' => null,
            ],
        ],
        [
            'later' => [
                'data' => 'another value',
            ],
        ],
    ],
    $chunks
);

You can also set up the in-memory stream manually:

$this->setUpDeferStream();

# Lumen

Because the TestResponse class is not available in Lumen, you must use a different test trait:

<?php

namespace Tests;

+use Nuwave\Lighthouse\Testing\MakesGraphQLRequestsLumen;

abstract class TestCase extends Laravel\Lumen\Testing\TestCase
{
+   use MakesGraphQLRequestsLumen;
}

All the test helpers are called the same as in MakesGraphQLRequest, the only difference is that they return $this instead of a TestResponse. Assertions work differently as a result:

public function testHelloWorld(): void
{
    $this->graphQL(/** @lang GraphQL */ '
    {
        hello
    }
    ')->seeJson([
        'data' => [
            'hello' => 'world',
        ],
    ])->seeHeader('SomeHeader', 'value');
}

← Complex Where Conditions Static Analysis with PHPStan →