Update API docs for changeAuthState

Author: dmurvihill

API.md

@@ -169,26 +169,45 @@ ref.flush(); // added foo after null
 
 Authentication methods for simulating changes to the auth state of a Firebase reference.
 
-##### `changeAuthState(authData)` -> `undefined`
+##### `changeAuthState(user)` -> `undefined`
 
-Changes the active authentication credentials to the `authData` object. Before changing the authentication state, `changeAuthState` checks whether the `authData` object is deeply equal to the current authentication data. `onAuth` listeners will only be triggered if the data is not deeply equal. To simulate no user being authenticated, pass `null` for `authData`. This operation is queued until the next `flush`.
+Changes the active authentication credentials to the `authData` object.
+Before changing the authentication state, `changeAuthState` checks the
+`user` object against the current authentication data.
+`onAuthStateChanged` listeners will only be triggered if the data is not
+deeply equal.
 
-`authData` should adhere to the [documented schema](https://www.firebase.com/docs/web/api/firebase/onauth.html).
+To simulate no user being authenticated, pass `null` for `user`.
+This operation is queued until the next `flush`.
 
 Example:
 
 ```js
-ref.changeAuthState({
+ref.changeAuthState(new User(ref, {
   uid: 'theUid',
-  provider: 'github',
-  token: 'theToken',
-  expires: Math.floor(new Date() / 1000) + 24 * 60 * 60, // expire in 24 hours
-  auth: {
-    myAuthProperty: true
-  }
-});
+  email: '[email protected]',
+  emailVerified: true,
+  displayName: 'Mr. Meeseeks',
+  phoneNumber: '+1-508-123-4567',
+  photoURL: 'https://example.com/image.png',
+  isAnonymous: false,
+  providerId: 'github',
+  providerData: [],
+  refreshToken: '123e4567-e89b-12d3-a456-426655440000',
+  metadata: {},  // firebase-mock offers limited support for this field
+  customClaims: {
+    isAdmin: true,
+    // etc.
+  },
+  _idtoken: 'theToken',
+  _tokenValidity: {
+    authTime: '2019-11-22T08:46:15Z',
+    issuedAtTime: '2019-11-22T08:46:15Z',
+    expirationTime: '2019-11-22T09:46:15Z',
+  },
+}));
 ref.flush();
-console.assert(ref.getAuth().auth.myAuthProperty, 'authData has custom property');
+console.assert(ref.getAuth().displayName === 'Mr. Meeseeks', 'Auth name is correct');
 ```
 
 <hr>

test/unit/docs.js

@@ -0,0 +1,40 @@
+const User = require('../../src/user');
+
+describe('API.md', () => {
+  describe('Auth example for', () => {
+
+    let ref;
+    beforeEach(() => {
+      const Authentication = require('../../').MockAuthentication;
+      ref = new Authentication();
+    });
+
+    it('changeAuthState works as described', () => {
+      ref.changeAuthState(new User(ref, {
+        uid: 'theUid',
+        email: '[email protected]',
+        emailVerified: true,
+        displayName: 'Mr. Meeseeks',
+        phoneNumber: '+1-508-123-4567',
+        photoURL: 'https://example.com/image.png',
+        isAnonymous: false,
+        providerId: 'github',
+        providerData: [],
+        refreshToken: '123e4567-e89b-12d3-a456-426655440000',
+        metadata: {},  // firebase-mock offers limited support for this field
+        customClaims: {
+          isAdmin: true,
+          // etc.
+        },
+        _idtoken: 'theToken',
+        _tokenValidity: {
+          authTime: '2019-11-22T08:46:15Z',
+          issuedAtTime: '2019-11-22T08:46:15Z',
+          expirationTime: '2019-11-22T09:46:15Z',
+        },
+      }));
+      ref.flush();
+      console.assert(ref.getAuth().displayName === 'Mr. Meeseeks', 'Auth name is correct');
+    });
+  });
+});