refactor(fdc): Pythonic impersonation representation and test suite cleanup

- Impersonation API: Updated Impersonation to use auth_claims (snake_case) in Python land, while translating it to authClaims (camelCase) in _prepare_graphql_payload during JSON wire serialization.
- Impersonation Validation: Updated _validate_impersonation_options to validate auth_claims in Python land.
- Integration Tests (integration/test_data_connect.py): Added UPDATED_FRED_EMAIL mutation test fixtures with real state changes, restored initial state via UPSERT_FRED_EMAIL cleanup at the end of mutation tests, reordered query tests before mutations, and removed redundant read impersonation test cases.

Author: mk2023

firebase_admin/dataconnect.py

@@ -131,7 +131,7 @@ def __init__(
         else:
             if not isinstance(auth_claims, dict):
                 raise ValueError("'auth_claims' must be a dictionary.")
-            super().__init__(authClaims=auth_claims)
+            super().__init__(auth_claims=auth_claims)
 
     @staticmethod
     def unauthenticated() -> 'Impersonation':
@@ -364,22 +364,22 @@ def _validate_impersonation_options(self, impersonate: Any) -> None:
         if impersonate is not None:
             if not isinstance(impersonate, dict):
                 raise ValueError('impersonate option must be a dictionary')
-            if 'unauthenticated' not in impersonate and 'authClaims' not in impersonate:
+            if 'unauthenticated' not in impersonate and 'auth_claims' not in impersonate:
                 raise ValueError(
                     "impersonate option must contain either "
-                    "'unauthenticated' or 'authClaims'"
+                    "'unauthenticated' or 'auth_claims'"
                 )
-            if 'unauthenticated' in impersonate and 'authClaims' in impersonate:
+            if 'unauthenticated' in impersonate and 'auth_claims' in impersonate:
                 raise ValueError(
                     "impersonate option cannot contain both "
-                    "'unauthenticated' and 'authClaims'"
+                    "'unauthenticated' and 'auth_claims'"
                 )
             if 'unauthenticated' in impersonate:
                 if not isinstance(impersonate['unauthenticated'], bool):
                     raise ValueError("'unauthenticated' claim must be a boolean")
-            if 'authClaims' in impersonate:
-                if not isinstance(impersonate['authClaims'], dict):
-                    raise ValueError("'authClaims' claim must be a dictionary")
+            if 'auth_claims' in impersonate:
+                if not isinstance(impersonate['auth_claims'], dict):
+                    raise ValueError("'auth_claims' claim must be a dictionary")
 
     def _validate_graphql_options(
         self,
@@ -426,8 +426,11 @@ def _prepare_graphql_payload(
                 payload["operationName"] = graphql_options.operation_name.strip()
 
             if graphql_options.impersonate is not None:
+                impersonate_payload = dict(graphql_options.impersonate)
+                if "auth_claims" in impersonate_payload:
+                    impersonate_payload["authClaims"] = impersonate_payload.pop("auth_claims")
                 payload["extensions"] = {
-                    "impersonate": graphql_options.impersonate
+                    "impersonate": impersonate_payload
                 }
 
         return payload

integration/test_data_connect.py

@@ -40,6 +40,14 @@
     'from': {'id': FRED_USER['id']}
 }
 
+UPDATED_FRED_EMAIL = {
+    'id': FRED_EMAIL['id'],
+    'subject': 'updated subject',
+    'date': '2026-07-31',
+    'text': 'updated body text!',
+    'from': {'id': FRED_USER['id']}
+}
+
 INITIAL_STATE = {
     'users': [FRED_USER, JEFF_USER],
     'emails': [FRED_EMAIL]
@@ -97,6 +105,17 @@
       }})
     }}"""
 
+UPSERT_UPDATED_FRED_EMAIL = f"""
+    mutation email {{
+      email_upsert(data: {{
+        id:"{UPDATED_FRED_EMAIL['id']}",
+        subject: "{UPDATED_FRED_EMAIL['subject']}",
+        date: "{UPDATED_FRED_EMAIL['date']}",
+        text: "{UPDATED_FRED_EMAIL['text']}",
+        fromId: "{UPDATED_FRED_EMAIL['from']['id']}"
+      }})
+    }}"""
+
 DELETE_ALL = """
     mutation delete {
       email_deleteMany(all: true)
@@ -125,33 +144,22 @@
 class TestExecuteGraphql:
     """Integration tests for execute_graphql method."""
 
-    def test_execute_graphql_mutation(self):
-        """Tests executing mutations via execute_graphql."""
-        dc_client = dataconnect.client(CONNECTOR_CONFIG)
-        fred_resp = dc_client.execute_graphql(UPSERT_FRED_USER)
-        assert fred_resp.data['user_upsert']['id'] == FRED_USER['id']
-
-        jeff_resp = dc_client.execute_graphql(UPSERT_JEFF_USER)
-        assert jeff_resp.data['user_upsert']['id'] == JEFF_USER['id']
-
-        upsert_email_resp = dc_client.execute_graphql(UPSERT_FRED_EMAIL)
-        email_id = upsert_email_resp.data['email_upsert']['id']
-        assert email_id
-
-        get_email_options = dataconnect.GraphqlOptions(variables={'id': email_id})
-        query_email_resp = dc_client.execute_graphql(
-            QUERY_GET_EMAIL, options=get_email_options
-        )
-        assert query_email_resp.data['email'] == FRED_EMAIL
-
     def test_execute_graphql_query(self):
         """Tests executing a query via execute_graphql."""
         dc_client = dataconnect.client(CONNECTOR_CONFIG)
         resp = dc_client.execute_graphql(QUERY_LIST_USERS)
-        assert sorted(resp.data['users'], key=lambda x: x['id']) == sorted(
-            INITIAL_STATE['users'], key=lambda x: x['id']
+        assert sorted(resp.data['users'], key=lambda user: user['id']) == sorted(
+            INITIAL_STATE['users'], key=lambda user: user['id']
         )
 
+    def test_execute_graphql_query_with_variables(self):
+        """Tests query execution with variables."""
+        dc_client = dataconnect.client(CONNECTOR_CONFIG)
+        user_id = INITIAL_STATE['users'][0]['id']
+        options = dataconnect.GraphqlOptions(variables={'id': {'id': user_id}})
+        resp = dc_client.execute_graphql(QUERY_GET_USER_BY_ID, options=options)
+        assert resp.data['user'] == INITIAL_STATE['users'][0]
+
     def test_execute_graphql_operation_name_multiple_queries(self):
         """Tests operation_name with multi-query document."""
         dc_client = dataconnect.client(CONNECTOR_CONFIG)
@@ -166,13 +174,25 @@ def test_execute_graphql_query_error_missing_variables(self):
             dc_client.execute_graphql(QUERY_GET_USER_BY_ID)
         assert excinfo.value.code == 'query-error'
 
-    def test_execute_graphql_query_with_variables(self):
-        """Tests query execution with variables."""
+    def test_execute_graphql_mutation(self):
+        """Tests executing mutations via execute_graphql."""
         dc_client = dataconnect.client(CONNECTOR_CONFIG)
-        user_id = INITIAL_STATE['users'][0]['id']
-        options = dataconnect.GraphqlOptions(variables={'id': {'id': user_id}})
-        resp = dc_client.execute_graphql(QUERY_GET_USER_BY_ID, options=options)
-        assert resp.data['user'] == INITIAL_STATE['users'][0]
+        fred_resp = dc_client.execute_graphql(UPSERT_FRED_USER)
+        assert fred_resp.data['user_upsert']['id'] == FRED_USER['id']
+
+        jeff_resp = dc_client.execute_graphql(UPSERT_JEFF_USER)
+        assert jeff_resp.data['user_upsert']['id'] == JEFF_USER['id']
+
+        upsert_email_resp = dc_client.execute_graphql(UPSERT_UPDATED_FRED_EMAIL)
+        email_id = upsert_email_resp.data['email_upsert']['id']
+        assert email_id == UPDATED_FRED_EMAIL['id']
+
+        get_email_options = dataconnect.GraphqlOptions(variables={'id': email_id})
+        query_email_resp = dc_client.execute_graphql(
+            QUERY_GET_EMAIL, options=get_email_options
+        )
+        assert query_email_resp.data['email'] == UPDATED_FRED_EMAIL
+        dc_client.execute_graphql(UPSERT_FRED_EMAIL)
 
 
 class TestExecuteGraphqlRead:
@@ -182,8 +202,8 @@ def test_execute_graphql_read_query(self):
         """Tests read-only query execution."""
         dc_client = dataconnect.client(CONNECTOR_CONFIG)
         resp = dc_client.execute_graphql_read(QUERY_LIST_USERS)
-        assert sorted(resp.data['users'], key=lambda x: x['id']) == sorted(
-            INITIAL_STATE['users'], key=lambda x: x['id']
+        assert sorted(resp.data['users'], key=lambda user: user['id']) == sorted(
+            INITIAL_STATE['users'], key=lambda user: user['id']
         )
 
     def test_execute_graphql_read_mutation_fails(self):
@@ -273,8 +293,8 @@ def test_impersonated_authenticated(self):
             resp = dc_client.execute_graphql(
                 QUERY_LIST_USERS, options=OPTS_AUTHORIZED_FRED_CLAIMS
             )
-            assert sorted(resp.data['users'], key=lambda x: x['id']) == sorted(
-                INITIAL_STATE['users'], key=lambda x: x['id']
+            assert sorted(resp.data['users'], key=lambda user: user['id']) == sorted(
+                INITIAL_STATE['users'], key=lambda user: user['id']
             )
 
         def test_impersonated_unauthenticated(self):
@@ -283,8 +303,8 @@ def test_impersonated_unauthenticated(self):
             resp = dc_client.execute_graphql(
                 QUERY_LIST_USERS, options=OPTS_UNAUTHORIZED_CLAIMS
             )
-            assert sorted(resp.data['users'], key=lambda x: x['id']) == sorted(
-                INITIAL_STATE['users'], key=lambda x: x['id']
+            assert sorted(resp.data['users'], key=lambda user: user['id']) == sorted(
+                INITIAL_STATE['users'], key=lambda user: user['id']
             )
 
         def test_impersonated_non_existing_claims(self):
@@ -293,8 +313,8 @@ def test_impersonated_non_existing_claims(self):
             resp = dc_client.execute_graphql(
                 QUERY_LIST_USERS, options=OPTS_NON_EXISTING_CLAIMS
             )
-            assert sorted(resp.data['users'], key=lambda x: x['id']) == sorted(
-                INITIAL_STATE['users'], key=lambda x: x['id']
+            assert sorted(resp.data['users'], key=lambda user: user['id']) == sorted(
+                INITIAL_STATE['users'], key=lambda user: user['id']
             )
 
 

tests/test_data_connect.py

@@ -39,7 +39,7 @@
 TEST_HEADERS = {"key": "val"}
 TEST_PAYLOAD = {"query": TEST_QUERY}
 TEST_AUTH_CLAIMS = {"sub": "user_123"}
-TEST_VARIABLES = {"foo": "bar"}
+TEST_VARIABLES = {"var_key": "var_val"}
 
 @dataclass
 class UserProfile:
@@ -481,11 +481,11 @@ def test_validate_graphql_options_invalid_impersonate(self):
         with pytest.raises(ValueError, match="impersonate option must be a dictionary"):
             self.api_client._validate_graphql_options(options)
 
-        # impersonate must have either unauthenticated or authClaims
+        # impersonate must have either unauthenticated or auth_claims
         options = dataconnect.GraphqlOptions(impersonate={"invalid_key": True})
         msg = (
             "impersonate option must contain either "
-            "'unauthenticated' or 'authClaims'"
+            "'unauthenticated' or 'auth_claims'"
         )
         with pytest.raises(ValueError, match=msg):
             self.api_client._validate_graphql_options(options)
@@ -495,18 +495,18 @@ def test_validate_graphql_options_invalid_impersonate(self):
         with pytest.raises(ValueError, match="'unauthenticated' claim must be a boolean"):
             self.api_client._validate_graphql_options(options)
 
-        # authClaims must be a dict
-        options = dataconnect.GraphqlOptions(impersonate={"authClaims": "not-dict"})
-        with pytest.raises(ValueError, match="'authClaims' claim must be a dictionary"):
+        # auth_claims must be a dict
+        options = dataconnect.GraphqlOptions(impersonate={"auth_claims": "not-dict"})
+        with pytest.raises(ValueError, match="'auth_claims' claim must be a dictionary"):
             self.api_client._validate_graphql_options(options)
 
-        # impersonate cannot contain both unauthenticated and authClaims
+        # impersonate cannot contain both unauthenticated and auth_claims
         options = dataconnect.GraphqlOptions(
-            impersonate={"unauthenticated": True, "authClaims": {"uid": "123"}}
+            impersonate={"unauthenticated": True, "auth_claims": {"uid": "123"}}
         )
         msg = (
             "impersonate option cannot contain both "
-            "'unauthenticated' and 'authClaims'"
+            "'unauthenticated' and 'auth_claims'"
         )
         with pytest.raises(ValueError, match=msg):
             self.api_client._validate_graphql_options(options)
@@ -564,7 +564,7 @@ def teardown_method(self, method):
 
     def test_prepare_graphql_payload_only_query(self):
         payload = self.api_client._prepare_graphql_payload(TEST_QUERY, None)
-        assert payload == {"query": TEST_QUERY}
+        assert payload == TEST_PAYLOAD
 
     def test_prepare_graphql_payload_with_variables(self):
         options = dataconnect.GraphqlOptions(variables=TEST_VARIABLES)
@@ -837,7 +837,7 @@ def test_unauthenticated_factory(self):
     def test_authenticated_factory(self):
         """Tests factory method for authenticated impersonation."""
         imp = dataconnect.Impersonation.authenticated(TEST_AUTH_CLAIMS)
-        assert imp == {"authClaims": TEST_AUTH_CLAIMS}
+        assert imp == {"auth_claims": TEST_AUTH_CLAIMS}
 
     def test_constructor_unauthenticated(self):
         """Tests direct constructor with unauthenticated=True."""
@@ -847,7 +847,7 @@ def test_constructor_unauthenticated(self):
     def test_constructor_auth_claims(self):
         """Tests direct constructor with auth_claims dict."""
         imp = dataconnect.Impersonation(auth_claims=TEST_AUTH_CLAIMS)
-        assert imp == {"authClaims": TEST_AUTH_CLAIMS}
+        assert imp == {"auth_claims": TEST_AUTH_CLAIMS}
 
     def test_constructor_neither_unauth_nor_claims_fails(self):
         """Tests specifying neither unauthenticated nor claims raises ValueError."""
@@ -971,7 +971,7 @@ def test_execute_graphql_payload_omits_empty_fields(self, mock_make_gql_request)
         mock_make_gql_request.assert_called_once_with(
             url=mock.ANY,
             headers=mock.ANY,
-            payload={"query": TEST_QUERY}
+            payload=TEST_PAYLOAD
         )
 
     @mock.patch.object(_http_client.JsonHttpClient, "body_and_response")