README

An extension for Laravel Socialite designed to streamline testing. This package provides simple, expressive fake classes that allow you to write deterministic tests for OAuth flows without making any real API calls to external providers. The package seamlessly integrates with and enhances the core functionality of laravel/socialite.

Requirements

PHP: ^8.3
Laravel Socialite: ^5.23
Laravel: 11.x (compatible with the Socialite version above)

Installation

Install the package via Composer:

composer require --dev cndrsdrmn/socialite

The service provider is automatically registered and enhances Socialite's factory in non-production environments. No manual configuration is required for basic usage.

Quickstart

You can use the Socialite facade to fake its behavior and assert on redirects and returned users. This works seamlessly with both Pest and PHPUnit.

Faking and Redirect Assertions

use Laravel\Socialite\Facades\Socialite;

it('fakes socialite and tracks redirects', function () {
    Socialite::fake();

    // Assert that no redirect has happened yet.
    Socialite::assertNotRedirected();

    // Trigger a redirect using the default fake driver.
    $response = Socialite::driver('default')->redirect();

    // Assert that a redirect was correctly tracked.
    Socialite::assertRedirected();

    expect($response->getStatusCode())->toBe(302);
    expect($response->headers->get('X-Socialite-Fake'))->toBe('1');
});

Configuring Fake Users

To set specific user data for a provider, pass an array of attributes to the fake() method. The fake will return a Laravel\Socialite\User instance populated with your provided data.

use Laravel\Socialite\Facades\Socialite;

it('returns a fake user with configured attributes', function () {
    Socialite::fake([
        'github' => [
            'id' => 'user-1',
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'nickname' => 'john.doe',
            'avatar' => 'https://example.com/john.jpg',
        ],
    ]);

    $user = Socialite::driver('github')->user();

    // Use the built-in assertions to verify the user data.
    Socialite::assertUser([
        'id' => 'user-1',
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'nickname' => 'john.doe',
        'avatar' => 'https://example.com/john.jpg',
    ]);

    // You can also assert directly on the returned user object.
    expect($user->getId())->toBe('user-1');
});

If you call Socialite::fake() without any parameters, all providers are faked by default. Any driver not explicitly configured will return a default fake user.

Default User Attributes:

[
    'id' => 'uuid-v4',
    'name' => 'Fake User',
    'email' => 'fake@example.com',
    'nickname' => 'fake',
    'avatar' => 'https://example.com/avatar.jpg',
]

Simulating Failures

To test your application's error handling, you can configure the fake to throw an exception when user() is called.

use Exception;
use Laravel\Socialite\Facades\Socialite;

Socialite::fake(withFailure: new Exception('Boom'));

// The following line will now throw the configured exception.
expect(fn () => Socialite::driver('github')->user())
    ->toThrow(Exception::class);

Available Assertions

Assertion	Description
`Socialite::assertRedirected()`	Checks that a redirect occurred through the Socialite fake.
`Socialite::assertNotRedirected()`	Verifies that a redirect has not yet occurred.
`Socialite::assertUser(array $attributes)`	Confirms the fake user object includes the specified attributes and values.
`Socialite::assertUserHasAttribute(string $attribute, mixed $value)`	Checks that the fake user object has a specific attribute with a given value.
`Socialite::assertStateless()`	Verifies that stateless has been invoked in the current chain.
`Socialite::assertNotStateless()`	Verifies that stateless has not been invoked in the curren chain.

License

This package is open-sourced software licensed under The MIT License (MIT). See the LICENSE file for more details.

Credits

Built by: Candra Sudirman
Inspired by: The streamlined testing workflows found in the Laravel framework.
Package Template: Skeleton PHP

cndrsdrmn / socialite

Maintainers

Details