fix(auth, useUserAccessGroup): document auth/keychain-error, add test…

… coverage

The update to firebase-ios-sdk v7.8.0 which fixed an underlying useUserAccessGroup issue
exposed an error in the E2E test that covers our wrapper for the method when it started
returning an error in a legitimately incorrect usage.

This patches up the test case and documents the error that may be thrown

Fixes #5007

packages/auth/e2e/auth.e2e.js

@@ -1045,8 +1045,11 @@ describe('auth()', function () {
   });
 
   describe('useUserAccessGroup()', function () {
-    it('should return "null" on successful keychain implementation', async function () {
-      const successfulKeychain = await firebase.auth().useUserAccessGroup('mysecretkeychain');
+    // Android simply does Promise.resolve, that is sufficient for this test multi-platform
+    it('should return "null" when accessing a group that exists', async function () {
+      const successfulKeychain = await firebase
+        .auth()
+        .useUserAccessGroup('YYX2P3XVJ7.com.invertase.testing'); // iOS signing team is YYX2P3XVJ7
 
       should.not.exist(successfulKeychain);
 
@@ -1055,5 +1058,17 @@ describe('auth()', function () {
 
       should.not.exist(resetKeychain);
     });
+
+    it('should throw when requesting an inaccessible group', async function () {
+      // Android will never throw, so this test is iOS only
+      if (device.getPlatform() === 'ios') {
+        try {
+          await firebase.auth().useUserAccessGroup('there.is.no.way.this.group.exists');
+          throw new Error('Should have thrown an error for inaccessible group');
+        } catch (e) {
+          e.message.should.containEql('auth/keychain-error');
+        }
+      }
+    });
   });
 });

packages/auth/lib/index.d.ts

@@ -1638,6 +1638,7 @@ export namespace FirebaseAuthTypes {
      *
      * @platform ios
      *
+     * @error auth/keychain-error Thrown if you attempt to access an inaccessible keychain
      * @param userAccessGroup A string of the keychain id i.e. "TEAMID.com.example.group1"
      */
     useUserAccessGroup(userAccessGroup: string): Promise<null>;