docs: explain required role-permissions (#220)

* docs: explain required role-permissions

* pr-fix: change cosmos db title

* pr-fix: correct w/ possible 404 if already deleted

* pr-fix: correct pk var

* pr-fix: remove unnecessary 404 check

* Update docs/preview/02-Features/04-Storage/02-cosmos.mdx

Author: stijnmoreels

docs/preview/02-Features/04-Storage/01-storage-account.mdx

@@ -15,6 +15,8 @@ The following functionality is available when installing this package:
 PM> Install-Package -Name Arcus.Testing.Storage.Blob
 ```
 
+> 🛡️ Make sure that the test client that interacts with the Blob storage has at least [`Storage Blob Data Contributor`](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor)-rights if the test needs to create/update/delete containers.
+
 ## Temporary Blob container
 The `TemporaryBlobContainer` provides a solution when the integration test requires a storage system (container) during the test run. An Azure Blob container is created upon the setup of the test fixture and is deleted again when the test fixture is disposed.
 
@@ -171,6 +173,8 @@ The following functionality is available when installing this package:
 PM> Install-Package -Name Arcus.Testing.Storage.Table
 ```
 
+> 🛡️ Make sure that the test client that interacts with the Table storage has at least [`Storage Table Data Contributor`](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/storage#storage-table-data-contributor)-rights if the test needs to create/update/delete tables.
+
 ## Temporary Table
 The `TemporaryTable` provides a solution when the integration test requires a storage system (table) during the test run. An Azure Table is created upon the setup of the test fixture and is deleted again when the test fixture is disposed.
 

docs/preview/02-Features/04-Storage/02-cosmos.mdx

@@ -1,7 +1,7 @@
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# CosmosDb storage
+# CosmosDb
 The `Arcus.Testing.Storage.CosmosDb` package provides test fixtures to Azure CosmosDb storage. By using the common test practices 'clean environment', it provides a temporary collections and documents.
 
 ## Installation
@@ -14,6 +14,8 @@ PM> Install-Package -Name Arcus.Testing.Storage.Cosmos
 <Tabs groupId="storage-types">
 <TabItem value="mongodb" label="MongoDb" default>
 
+> 🛡️ Make sure that the test client that interacts with the Cosmos storage has at least [`DocumentDB Account Contributor`](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/databases#documentdb-account-contributor)-rights if the test needs to create/update/delete collections.
+
 ### Temporary MongoDb collection
 The `TemporaryMongoDbCollection` provides a solution when the integration tes requires a storage system (collection) during the test run. An MongoDb collection is created upon setup of the test fixture and is deleted again when the test fixture disposed.
 
@@ -124,6 +126,18 @@ BsonValue documentId = document.Id;
 </TabItem>
 <TabItem value="nosql" label="NoSql">
 
+> 🛡️ Make sure that the test client that interacts with the Cosmos storage has at least [`Cosmos DB Built-in Data Contributor`](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/security/reference-data-plane-roles)-rights if the test needs to create/update/delete containers.
+> 
+> **This role is not a built-in Azure RBAC, but a role specific for NoSql**. One can [assign this role with Azure CLI](https://learn.microsoft.com/en-us/cli/azure/cosmosdb/sql/role/assignment?view=azure-cli-latest#az-cosmosdb-sql-role-assignment-create):
+> ```shell
+> az cosmosdb sql role assignment create `
+>   --account-name "CosmosDBAccountName" `
+>   --resource-group "ResourceGroupName" `
+>   --role-definition-name "Cosmos DB Built-in Data Contributor" `
+>   --scope "/" `
+>   --principal-id "UserOrPrincipalObjectId"
+> ```
+
 ### Temporary NoSql container
 The `TemporaryNoSqlContainer` provides a solution when the integration tes requires a storage system (container) during the test run. A NoSql container is created upon setup of the test fixture and is deleted again when the test fixture disposed.
 

src/Arcus.Testing.Storage.Cosmos/TemporaryNoSqlContainer.cs

@@ -3,6 +3,7 @@
 using System.Collections.ObjectModel;
 using System.IO;
 using System.Linq;
+using System.Net;
 using System.Text;
 using System.Threading.Tasks;
 using Azure;
@@ -547,7 +548,14 @@ private static async Task CleanContainerOnSetupAsync(Container container, Tempor
                 await ForEachItemAsync(container, async (id, partitionKey, _) =>
                 {
                     logger.LogTrace("[Test:Setup] Delete Azure Cosmos NoSql item '{ItemId}' {PartitionKey} in container '{DatabaseName}/{ContainerName}'", id, partitionKey, container.Database.Id, container.Id);
-                    await container.DeleteItemStreamAsync(id, partitionKey);
+                    using ResponseMessage response = await container.DeleteItemStreamAsync(id, partitionKey);
+                    
+                    if (!response.IsSuccessStatusCode && response.StatusCode != HttpStatusCode.NotFound)
+                    {
+                        throw new RequestFailedException(
+                            $"[Test:Setup] Failed to delete Azure Cosmos NoSql item '{id}' {partitionKey} in container '{container.Database.Id}/{container.Id}' " +
+                            $"since the delete operation responded with a failure: {(int) response.StatusCode} {response.StatusCode}: {response.ErrorMessage}");
+                    }
                 });
             }
             else if (options.OnSetup.Items is OnSetupNoSqlContainer.CleanIfMatched)
@@ -557,7 +565,14 @@ await ForEachItemAsync(container, async (id, key, doc) =>
                     if (options.OnSetup.IsMatched(id, key, doc, container.Database.Client))
                     {
                         logger.LogTrace("[Test:Setup] Delete matched Azure Cosmos NoSql item '{ItemId}' {PartitionKey} in container '{DatabaseName}/{ContainerName}'", id, key, container.Database.Id, container.Id);
-                        await container.DeleteItemStreamAsync(id, key);
+                        using ResponseMessage response = await container.DeleteItemStreamAsync(id, key);
+
+                        if (!response.IsSuccessStatusCode && response.StatusCode != HttpStatusCode.NotFound)
+                        {
+                            throw new RequestFailedException(
+                                $"[Test:Setup] Failed to delete matched Azure Cosmos NoSql item '{id}' {key} in container '{container.Database.Id}/{container.Id}' " +
+                                $"since the delete operation responded with a failure: {(int) response.StatusCode} {response.StatusCode}: {response.ErrorMessage}");
+                        }
                     }
                 });
             }
@@ -594,18 +609,15 @@ public async ValueTask DisposeAsync()
             }
             else
             {
-                disposables.Add(AsyncDisposable.Create(async () =>
-                {
-                    await CleanContainerOnTeardownAsync();
-                }));
+                await CleanContainerOnTeardownAsync(disposables);
             }
 
             disposables.Add(_resourceClient);
 
             GC.SuppressFinalize(this);
         }
 
-        private async Task CleanContainerOnTeardownAsync()
+        private async Task CleanContainerOnTeardownAsync(DisposableCollection disposables)
         {
             if (_options.OnTeardown.Items is OnTeardownNoSqlContainer.CleanIfCreated)
             {
@@ -614,21 +626,45 @@ private async Task CleanContainerOnTeardownAsync()
 
             if (_options.OnTeardown.Items is OnTeardownNoSqlContainer.CleanAll)
             {
-                await ForEachItemAsync(async (id, key, _) =>
+                await ForEachItemAsync((id, key, _) =>
                 {
-                    _logger.LogTrace("[Test:Teardown] Delete Azure Cosmos NoSql item '{ItemId}' {PartitionKey} in NoSql container '{DatabaseName}/{ContainerName}'", id, key, Client.Database.Id, Client.Id);
-                    await Client.DeleteItemStreamAsync(id, key);
+                    disposables.Add(AsyncDisposable.Create(async () =>
+                    {
+                        _logger.LogTrace("[Test:Teardown] Delete Azure Cosmos NoSql item '{ItemId}' {PartitionKey} in NoSql container '{DatabaseName}/{ContainerName}'", id, key, Client.Database.Id, Client.Id);
+                        using ResponseMessage response = await Client.DeleteItemStreamAsync(id, key);
+                        
+                        if (!response.IsSuccessStatusCode && response.StatusCode != HttpStatusCode.NotFound)
+                        {
+                            throw new RequestFailedException(
+                                $"[Test:Teardown] Failed to delete Azure Cosmos NoSql item '{id}' {key} in container '{Client.Database.Id}/{Client.Id}' " +
+                                $"since the delete operation responded with a failure: {(int) response.StatusCode} {response.StatusCode}: {response.ErrorMessage}");
+                        }
+                    }));
+
+                    return Task.CompletedTask;
                 });
             }
             else if (_options.OnTeardown.Items is OnTeardownNoSqlContainer.CleanIfMatched)
             {
-                await ForEachItemAsync(async (id, key, doc) =>
+                await ForEachItemAsync((id, key, doc) =>
                 {
-                    if (_options.OnTeardown.IsMatched(id, key, doc, Client.Database.Client))
+                    disposables.Add(AsyncDisposable.Create(async () =>
                     {
-                        _logger.LogTrace("[Test:Teardown] Delete Azure Cosmos NoSql item '{ItemId}' {PartitionKey} in NoSql container '{DatabaseName}/{ContainerName}'", id, key, Client.Database.Id, Client.Id);
-                        await Client.DeleteItemStreamAsync(id, key);
-                    }
+                        if (_options.OnTeardown.IsMatched(id, key, doc, Client.Database.Client))
+                        {
+                            _logger.LogTrace("[Test:Teardown] Delete Azure Cosmos NoSql item '{ItemId}' {PartitionKey} in NoSql container '{DatabaseName}/{ContainerName}'", id, key, Client.Database.Id, Client.Id);
+                            using ResponseMessage response = await Client.DeleteItemStreamAsync(id, key);
+                            
+                            if (!response.IsSuccessStatusCode && response.StatusCode != HttpStatusCode.NotFound)
+                            {
+                                throw new RequestFailedException(
+                                    $"[Test:Teardown] Failed to delete matched Azure Cosmos NoSql item '{id}' {key} in container '{Client.Database.Id}/{Client.Id}' " +
+                                    $"since the delete operation responded with a failure: {(int) response.StatusCode} {response.StatusCode}: {response.ErrorMessage}");
+                            }
+                        }
+                    }));
+
+                    return Task.CompletedTask;
                 });
             }
         }

src/Arcus.Testing.Storage.Cosmos/TemporaryNoSqlItem.cs

@@ -118,7 +118,7 @@ private static async Task<TemporaryNoSqlItem> InsertNewItemAsync<TItem>(
         {
             logger.LogDebug("[Test:Setup] Insert new Azure Cosmos NoSql '{ItemType}' item '{ItemId}' to container '{DatabaseName}/{ContainerName}'", typeof(TItem).Name, itemId, container.Database.Id, container.Id);
             ItemResponse<TItem> response = await container.CreateItemAsync(item);
-            
+
             if (response.StatusCode != HttpStatusCode.Created)
             {
                 throw new RequestFailedException(
@@ -141,15 +141,29 @@ public async ValueTask DisposeAsync()
                 disposables.Add(AsyncDisposable.Create(async () =>
                 {
                     _logger.LogDebug("[Test:Teardown] Delete Azure Cosmos NoSql '{ItemType}' item '{ItemId}' in container '{DatabaseName}/{ContainerName}'", _itemType.Name, Id, _container.Database.Id, _container.Id);
-                    await _container.DeleteItemStreamAsync(Id, PartitionKey);
+                    using ResponseMessage response = await _container.DeleteItemStreamAsync(Id, PartitionKey);
+                    
+                    if (!response.IsSuccessStatusCode && response.StatusCode != HttpStatusCode.NotFound)
+                    {
+                        throw new RequestFailedException(
+                            $"[Test:Teardown] Failed to delete Azure Cosmos NoSql '{_itemType.Name}' item '{Id}' {PartitionKey} in container '{_container.Database.Id}/{_container.Id}' " +
+                            $"since the delete operation responded with a failure: {(int) response.StatusCode} {response.StatusCode}: {response.ErrorMessage}");
+                    }
                 }));
             }
             else
             {
                 disposables.Add(AsyncDisposable.Create(async () =>
                 {
                     _logger.LogDebug("[Test:Teardown] Revert replaced Azure Cosmos NoSql '{ItemType}' item '{ItemId}' in container '{DatabaseName}/{ContainerName}'", _itemType.Name, Id, _container.Database.Id, _container.Id);
-                    await _container.ReplaceItemStreamAsync(_originalItemStream, Id, PartitionKey);
+                    using ResponseMessage response = await _container.ReplaceItemStreamAsync(_originalItemStream, Id, PartitionKey);
+                    
+                    if (!response.IsSuccessStatusCode)
+                    {
+                        throw new RequestFailedException(
+                            $"[Test:Teardown] Failed to revert Azure Cosmos NoSql '{_itemType.Name}' item '{Id}' {PartitionKey} in container '{_container.Database.Id}/{_container.Id}' " +
+                            $"since the replace operation responded with a failure: {(int) response.StatusCode} {response.StatusCode}: {response.ErrorMessage}");
+                    }
                 }));
                 disposables.Add(AsyncDisposable.Create(async () =>
                 {