adding documentation

Author: dibahlfi

sdk/cosmos/azure-cosmos/tests/test_aad.py

@@ -89,13 +89,25 @@ def get_token(self, *scopes, **kwargs):
 
 @pytest.mark.cosmosEmulator
 @pytest.mark.cosmosAAD
+@pytest.mark.skipif(
+    not test_config.TestConfig.is_emulator
+    and test_config.TestConfig.data_auth_mode != 'aad',
+    reason="On a live account, run this file with COSMOS_TEST_DATA_AUTH_MODE=aad "
+           "so the dual-client factory returns the AAD branch. Otherwise the "
+           "test would silently use the master key and `delete_database` would "
+           "succeed instead of returning the asserted 403.",
+)
 class TestAAD(unittest.TestCase):
     client: cosmos_client.CosmosClient = None
     database: DatabaseProxy = None
     container: ContainerProxy = None
     configs = test_config.TestConfig
     host = configs.host
     masterKey = configs.masterKey
+    # Emulator-only: the hand-crafted JWT lets us exercise the AAD code path
+    # against the local emulator (which has no real AAD endpoint). On a live
+    # account this attribute is unused; setUpClass routes through the dual-client
+    # factory below instead.
     credential = CosmosEmulatorCredential() if configs.is_emulator else configs.credential
     _skip_scope_tests_on_non_emulator = pytest.mark.skipif(
         not configs.is_emulator,
@@ -104,7 +116,23 @@ class TestAAD(unittest.TestCase):
 
     @classmethod
     def setUpClass(cls):
-        cls.client = cosmos_client.CosmosClient(cls.host, cls.credential)
+        # Two construction paths:
+        #
+        #   * Emulator runs (`pytest -m cosmosEmulator`): build the client
+        #     directly with `CosmosEmulatorCredential` so the AAD JWT-parsing
+        #     code path is exercised against the local emulator. The dual-client
+        #     factory cannot do this — on the emulator it returns the master-key
+        #     client and bypasses AAD entirely.
+        #
+        #   * Live runs (`pytest -m cosmosAAD` on the AAD lane, or any live
+        #     run with `COSMOS_TEST_DATA_AUTH_MODE=aad`): go through
+        #     `TestConfig.create_data_client()` so this test exercises the
+        #     same dual-client factory contract every other AAD-tagged test
+        #     uses. 
+        if cls.configs.is_emulator:
+            cls.client = cosmos_client.CosmosClient(cls.host, cls.credential)
+        else:
+            cls.client = test_config.TestConfig.create_data_client()
         cls.database = cls.client.get_database_client(cls.configs.TEST_DATABASE_ID)
         cls.container = cls.database.get_container_client(cls.configs.TEST_SINGLE_PARTITION_CONTAINER_ID)