document testing socialite

Author: taylorotwell

socialite.md

@@ -11,6 +11,7 @@
     - [Slack Bot Scopes](#slack-bot-scopes)
     - [Optional Parameters](#optional-parameters)
 - [Retrieving User Details](#retrieving-user-details)
+- [Testing](#testing)
 
 <a name="introduction"></a>
 ## Introduction
@@ -229,3 +230,66 @@ use Laravel\Socialite\Socialite;
 
 return Socialite::driver('google')->stateless()->user();
 ```
+
+<a name="testing"></a>
+## Testing
+
+Laravel Socialite provides a convenient way to test OAuth authentication flows without making actual requests to OAuth providers. The `fake` method allows you to mock the OAuth provider's behavior and define the user data that should be returned.
+
+<a name="faking-the-redirect"></a>
+#### Faking the Redirect
+
+To test that your application correctly redirects users to an OAuth provider, you may invoke the `fake` method before making a request to your redirect route. This will cause Socialite to return a redirect to a fake authorization URL instead of redirecting to the actual OAuth provider:
+
+```php
+use Laravel\Socialite\Socialite;
+
+test('user is redirected to github', function () {
+    Socialite::fake('github');
+
+    $response = $this->get('/auth/github/redirect');
+
+    $response->assertRedirect();
+});
+```
+
+<a name="faking-the-callback"></a>
+#### Faking the Callback
+
+To test your application's callback route, you may invoke the `fake` method and provide a `User` instance that should be returned when your application requests the user's details from the provider. The `User` instance may be created using the `map` method:
+
+```php
+use Laravel\Socialite\Socialite;
+use Laravel\Socialite\Two\User;
+
+test('user can login with github', function () {
+    Socialite::fake('github', (new User)->map([
+        'id' => 'github-123',
+        'name' => 'Jason Beggs',
+        'email' => '[email protected]',
+    ]));
+
+    $response = $this->get('/auth/github/callback');
+
+    $response->assertRedirect('/dashboard');
+
+    $this->assertDatabaseHas('users', [
+        'name' => 'Jason Beggs',
+        'email' => '[email protected]',
+        'github_id' => 'github-123',
+    ]);
+});
+```
+
+By default, the `User` instance will also include a `token` property. If needed, you may manually specify additional properties on the `User` instance:
+
+```php
+$fakeUser = (new User)->map([
+    'id' => 'github-123',
+    'name' => 'Jason Beggs',
+    'email' => '[email protected]',
+])->setToken('fake-token')
+  ->setRefreshToken('fake-refresh-token')
+  ->setExpiresIn(3600)
+  ->setApprovedScopes(['read', 'write'])
+```