update tests and some comments

Author: stephenarosaj

src/data-connect/data-connect-api.ts

@@ -58,7 +58,10 @@ export interface GraphqlOptions<Variables> {
   variables?: Variables;
 
   /**
-   * The name of the GraphQL operation. Required only if `query` contains multiple operations.
+   * The name of the GraphQL operation.
+   * Required for operations that interact with connectors, such as impersonateQuery and impersonateMutation.
+   * Required for operations that interact with services, such as executeGraphql, if 
+   * `query` contains multiple operations.
    */
   operationName?: string;
 

test/unit/data-connect/data-connect-api-client-internal.spec.ts

@@ -234,7 +234,9 @@ describe('DataConnectApiClient', () => {
 
   describe('impersonateQuery', () => {
     const unauthenticatedOptions: GraphqlOptions<unknown> = 
-      { operationName: 'operationName', impersonate: { unauthenticated: true } };
+      { operationName: 'unauthenticatedQuery', impersonate: { unauthenticated: true } };
+    const authenticatedOptions: GraphqlOptions<unknown> = 
+      { operationName: 'authenticatedQuery', impersonate: { authClaims: { sub: 'authenticated-UUID' } } };
 
     it('should reject when no operationName is provided', () => {
       apiClient.impersonateQuery({ impersonate: { unauthenticated: true } })
@@ -300,7 +302,7 @@ describe('DataConnectApiClient', () => {
         .should.eventually.be.rejected.and.deep.include(expected);
     });
 
-    it('should resolve with the GraphQL response on success', () => {
+    describe('should resolve with the GraphQL response on success', () => {
       interface UsersResponse {
         users: [
           user: {
@@ -310,11 +312,11 @@ describe('DataConnectApiClient', () => {
           }
         ];
       }
-      const stub = sandbox
-        .stub(HttpClient.prototype, 'send')
-        .resolves(utils.responseFrom(TEST_RESPONSE, 200));
-      return apiClient.impersonateQuery<UsersResponse, unknown>(unauthenticatedOptions)
-        .then((resp) => {
+      it('for an unauthenticated request', () => {
+        const stub = sandbox
+          .stub(HttpClient.prototype, 'send')
+          .resolves(utils.responseFrom(TEST_RESPONSE, 200));
+        return apiClient.impersonateQuery<UsersResponse, unknown>(unauthenticatedOptions).then((resp) => {
           expect(resp.data.users).to.be.not.empty;
           expect(resp.data.users[0].name).to.be.not.undefined;
           expect(resp.data.users[0].address).to.be.not.undefined;
@@ -329,6 +331,27 @@ describe('DataConnectApiClient', () => {
             }
           });
         });
+      });
+      it('for an authenticated request', () => {
+        const stub = sandbox
+          .stub(HttpClient.prototype, 'send')
+          .resolves(utils.responseFrom(TEST_RESPONSE, 200));
+        return apiClient.impersonateQuery<UsersResponse, unknown>(authenticatedOptions).then((resp) => {
+          expect(resp.data.users).to.be.not.empty;
+          expect(resp.data.users[0].name).to.be.not.undefined;
+          expect(resp.data.users[0].address).to.be.not.undefined;
+          expect(resp.data.users).to.deep.equal(TEST_RESPONSE.data.users);
+          expect(stub).to.have.been.calledOnce.and.calledWith({
+            method: 'POST',
+            url: `https://firebasedataconnect.googleapis.com/v1alpha/projects/test-project/locations/${connectorConfig.location}/services/${connectorConfig.serviceId}/connectors/${connectorConfig.connector}:impersonateQuery`,
+            headers: EXPECTED_HEADERS,
+            data: { 
+              operationName: authenticatedOptions.operationName, 
+              extensions: { impersonate: authenticatedOptions.impersonate }
+            }
+          });
+        });
+      });
     });
 
     it('should use DATA_CONNECT_EMULATOR_HOST if set', () => {
@@ -351,10 +374,12 @@ describe('DataConnectApiClient', () => {
     });
   });
 
-  describe('impersonateMutation', () => {
-    const unauthenticatedOptions: GraphqlOptions<unknown> = 
-      { operationName: 'operationName', impersonate: { unauthenticated: true } };
+  const unauthenticatedOptions: GraphqlOptions<unknown> = 
+    { operationName: 'operationName', impersonate: { unauthenticated: true } };
+  const authenticatedOptions: GraphqlOptions<unknown> = 
+    { operationName: 'operationName', impersonate: { unauthenticated: true } };
 
+  describe('impersonateMutation', () => {
     it('should reject when no operationName is provided', () => {
       apiClient.impersonateMutation({ impersonate: { unauthenticated: true } })
         .should.eventually.be.rejectedWith('`query` must be a non-empty string.');
@@ -419,7 +444,61 @@ describe('DataConnectApiClient', () => {
         .should.eventually.be.rejected.and.deep.include(expected);
     });
 
-    it('should resolve with the GraphQL response on success', () => {
+    describe('should resolve with the GraphQL response on success', () => {
+      interface UsersResponse {
+        users: [
+          user: {
+            id: string;
+            name: string;
+            address: string;
+          }
+        ];
+      }
+      it('for an unauthenticated request', () => {
+        const stub = sandbox
+          .stub(HttpClient.prototype, 'send')
+          .resolves(utils.responseFrom(TEST_RESPONSE, 200));
+        return apiClient.impersonateMutation<UsersResponse, unknown>(unauthenticatedOptions)
+          .then((resp) => {
+            expect(resp.data.users).to.be.not.empty;
+            expect(resp.data.users[0].name).to.be.not.undefined;
+            expect(resp.data.users[0].address).to.be.not.undefined;
+            expect(resp.data.users).to.deep.equal(TEST_RESPONSE.data.users);
+            expect(stub).to.have.been.calledOnce.and.calledWith({
+              method: 'POST',
+              url: `https://firebasedataconnect.googleapis.com/v1alpha/projects/test-project/locations/${connectorConfig.location}/services/${connectorConfig.serviceId}/connectors/${connectorConfig.connector}:impersonateMutation`,
+              headers: EXPECTED_HEADERS,
+              data: { 
+                operationName: unauthenticatedOptions.operationName, 
+                extensions: { impersonate: unauthenticatedOptions.impersonate }
+              }
+            });
+          });
+      });
+      it('for an authenticated request', () => {
+        const stub = sandbox
+          .stub(HttpClient.prototype, 'send')
+          .resolves(utils.responseFrom(TEST_RESPONSE, 200));
+        return apiClient.impersonateMutation<UsersResponse, unknown>(authenticatedOptions)
+          .then((resp) => {
+            expect(resp.data.users).to.be.not.empty;
+            expect(resp.data.users[0].name).to.be.not.undefined;
+            expect(resp.data.users[0].address).to.be.not.undefined;
+            expect(resp.data.users).to.deep.equal(TEST_RESPONSE.data.users);
+            expect(stub).to.have.been.calledOnce.and.calledWith({
+              method: 'POST',
+              url: `https://firebasedataconnect.googleapis.com/v1alpha/projects/test-project/locations/${connectorConfig.location}/services/${connectorConfig.serviceId}/connectors/${connectorConfig.connector}:impersonateMutation`,
+              headers: EXPECTED_HEADERS,
+              data: { 
+                operationName: authenticatedOptions.operationName, 
+                extensions: { impersonate: authenticatedOptions.impersonate }
+              }
+            });
+          });
+      });
+    });
+
+    it('should resolve with the GraphQL response on success for an authenticated request', () => {
       interface UsersResponse {
         users: [
           user: {