feat(sb): add initial servicebus test components

build/deploy-test-resources.yml

@@ -38,6 +38,7 @@ stages:
             inputs:
               azureSubscription: '${{ parameters.azureServiceConnection }}'
               addSpnToEnvironment: true
+              failOnStandardError: true
               scriptType: 'pscore'
               scriptLocation: 'inlineScript'
               inlineScript: |
@@ -48,7 +49,7 @@ stages:
                   --parameters location=westeurope 
 
                 $objectId = (az ad sp show --id $env:servicePrincipalId | ConvertFrom-Json).id
-                $deployOutput = az deployment group create `
+                az deployment group create `
                   --resource-group ${{ parameters.resourceGroupName }} `
                   --template-file ./build/templates/test-resources.bicep `
                   --parameters location=westeurope `
@@ -58,6 +59,7 @@ stages:
                   --parameters cosmosDb_mongoDb_databaseName=${{ variables['Arcus.Testing.Cosmos.MongoDb.DatabaseName'] }} `
                   --parameters cosmosDb_noSql_name=${{ variables['Arcus.Testing.Cosmos.NoSql.Name'] }} `
                   --parameters cosmosDb_noSql_databaseName=${{ variables['Arcus.Testing.Cosmos.NoSql.DatabaseName'] }} `
+                  --parameters serviceBusNamespaceName=${{ variables['Arcus.Testing.ServiceBus.Namespace'] }} `
                   --parameters keyVaultName=${{ parameters.keyVaultName }} `
                   --parameters servicePrincipal_objectId=$objectId
 

build/templates/smoke-tests.ps1

@@ -28,7 +28,7 @@ Describe 'Storage account' {
         -DatabaseName $env:ARCUS_TESTING_COSMOS_MONGODB_DATABASENAME `
         -Name $collectionName
     }
-    catch {
+    finally {
       Remove-AzCosmosDBMongoDBCollection `
         -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
         -AccountName $env:ARCUS_TESTING_COSMOS_MONGODB_NAME `
@@ -44,14 +44,43 @@ Describe 'Storage account' {
         -AccountName $env:ARCUS_TESTING_COSMOS_NOSQL_NAME `
         -DatabaseName $env:ARCUS_TESTING_COSMOS_NOSQL_DATABASENAME `
         -Name $containerName `
-        -PartitionKeyPath '/pk'
+        -PartitionKeyPath '/pk' `
+        -PartitionKeyKind Hash
     }
-    catch {
+    finally {
       Remove-AzCosmosDBSqlContainer `
-      -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
-      -AccountName $env:ARCUS_TESTING_COSMOS_NOSQL_NAME `
-      -DatabaseName $env:ARCUS_TESTING_COSMOS_NOSQL_DATABASENAME `
-      -Name $containerName
+        -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
+        -AccountName $env:ARCUS_TESTING_COSMOS_NOSQL_NAME `
+        -DatabaseName $env:ARCUS_TESTING_COSMOS_NOSQL_DATABASENAME `
+        -Name $containerName
+    }
+  }
+  It "Service principal can create Service bus queue" {
+    $queueName = 'test-queue'
+    try {
+      New-AzServiceBusQueue `
+          -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
+          -NamespaceName $env:ARCUS_TESTING_SERVICEBUS_NAMESPACE `
+          -Name $queueName
+    } finally {
+      Remove-AzServiceBusQueue `
+        -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
+        -NamespaceName $env:ARCUS_TESTING_SERVICEBUS_NAMESPACE `
+        -Name $queueName
+    }
+  }
+  It "Service principal can create Service bus topic" {
+    $topicName = 'test-topic'
+    try {
+      New-AzServiceBusTopic `
+        -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
+        -NamespaceName $env:ARCUS_TESTING_SERVICEBUS_NAMESPACE `
+        -Name $topicName
+    } finally {
+      Remove-AzServiceBusTopic `
+        -ResourceGroupName $env:ARCUS_TESTING_RESOURCEGROUP_NAME `
+        -NamespaceName $env:ARCUS_TESTING_SERVICEBUS_NAMESPACE `
+        -Name $topicName
     }
   }
 }

build/templates/test-resources.bicep

@@ -19,6 +19,9 @@ param cosmosDb_noSql_name string
 // Define the name of the CosmosDb NoSql database that will be created.
 param cosmosDb_noSql_databaseName string
 
+// Define the name of the Service bus namespace resource that will be created.
+param serviceBusNamespaceName string
+
 // Define the name of the key vault where the necessary secrets will be stored to access the deployed test resources.
 param keyVaultName string
 
@@ -125,6 +128,26 @@ module cosmosDb_noSql 'br/public:avm/res/document-db/database-account:0.6.0' = {
   }
 }
 
+module serviceBusNamespace 'br/public:avm/res/service-bus/namespace:0.10.1' = {
+  name: 'serviceBusNamespaceDeployment'
+  params: {
+    name: serviceBusNamespaceName
+    location: location
+    enableTelemetry: false
+    publicNetworkAccess: 'Enabled'
+    skuObject: {
+      name: 'Standard'
+    }
+    zoneRedundant: false
+    roleAssignments: [
+      {
+        principalId: servicePrincipal_objectId
+        roleDefinitionIdOrName: 'Azure Service Bus Data Owner'
+      }
+    ]
+  }
+}
+
 module vault 'br/public:avm/res/key-vault/vault:0.6.1' = {
   name: 'vaultDeployment'
   params: {

build/variables/test.yml

@@ -1,12 +1,11 @@
 variables:
   Arcus.Testing.ResourceGroup.Name: 'arcus-testing-dev-we-rg'
-  Arcus.Testing.DataFactory.Name: 'arcus-testing-adf'
-
+  Arcus.Testing.DataFactory.Name: 'arcus-testing-adf'  
   Arcus.Testing.Cosmos.MongoDb.Name: 'arcus-testing-cosmos-mongo'
   Arcus.Testing.Cosmos.MongoDb.DatabaseName: 'arcus-testing-cosmos-mongo-db'
   Arcus.Testing.Cosmos.NoSql.Name: 'arcus-testing-cosmos-nosql'
-  Arcus.Testing.Cosmos.NoSql.DatabaseName: 'arcus-testing-cosmos-nosql-db'
-
+  Arcus.Testing.Cosmos.NoSql.DatabaseName: 'arcus-testing-cosmos-nosql-db'  
   Arcus.Testing.KeyVault.Name: 'arcus-testing-kv'
+  Arcus.Testing.ServiceBus.Namespace: 'arcus-testing-servicebus'
   Arcus.Testing.StorageAccount.Name: 'arcustestingstorage'
   Arcus.Testing.StorageAccount.Key.SecretName: 'Arcus-Testing-StorageAccount-Key'

docs/preview/02-Features/05-Messaging/01-servicebus.mdx

@@ -0,0 +1,234 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Service bus
+The `Arcus.Testing.Messaging.ServiceBus` package provides test fixtures related to Azure Service Bus. By using the common testing practice 'clean environment', it provides a temporary Topic (subscription) and queue.
+
+## Installation
+The following functionality is available when installing this package:
+
+```powershell
+PM> Install-Package -Name Arcus.Testing.Messaging.ServiceBus
+```
+
+<Tabs groupId="messaging-systems">
+<TabItem value="topic" label="Topic" default>
+
+## Temporary topic
+The `TemporaryTopic` provides a solution when the integration test requires an Azure Service Bus topic during the test run. A topic is created upon the setup of the test fixture and is deleted again when the test fixture is disposed.
+
+> ✨ Only when the test fixture was responsible for creating the topic, will the topic be deleted upon the fixture's disposal. This follows the 'clean environment' testing principle that describes that after the test run, the same state should be achieved as before the test run.
+
+```csharp
+using Arcus.Testing;
+
+await using var topic = await TemporaryTopic.CreateIfNotExistsAsync(
+  "<fully-qualified-namespace>", "<topic-name>", logger);
+```
+
+> ⚡ Uses by default the [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential) but other type of authentication mechanisms are supported with overloads.
+
+Adding subscriptions to the topic can also be done via the test fixture. It always makes sure that any added subscriptions are deleted again afterwards.
+
+```csharp
+using Arcus.Testing;
+
+await using TemporaryTopic topic = ...
+
+await topic.AddSubscriptionAsync("<subscription-name>");
+```
+
+### Customization
+The `TemporaryTopic` allows testers to configure setup/teardown operations on any messages that were on the topic subscriptions (or the topic itself) at the time of setup/teardown. This follows the 'clean environment' testing principle.
+
+```csharp
+using Arcus.Testing;
+
+await TemporaryTopic.CreateIfNotExistsAsync(..., options =>
+{
+    // Options related to when the test fixture is set up.
+    // ---------------------------------------------------
+
+    // Change the default topic-creation behavior.
+    options.OnSetup.CreateTopicWith((CreateTopicOptions opt) => ...);
+
+    // (Default) leave any existing messages on all the topic subscriptions. 
+    options.OnSetup.LeaveExistingMessages();
+
+    // Dead-letter any existing messages on all the topic subscriptions.
+    options.OnSetup.DeadLetterMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnSetup.DeadLetterMessages(TimeSpan.FromSeconds(10));
+    options.OnSetup.DeadLetterMessages((ServiceBusReceivedMessage msg) => 
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>");
+    });
+
+    // Complete any existing messages on all the topic subscriptions.
+    options.OnSetup.CompleteMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnSetup.CompleteMessages(TimeSpan.FromSeconds(10));
+    options.OnSetup.CompleteMessages((ServiceBusReceivedMessage msg) =>
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>"); 
+    });
+
+    // Options related to when the test fixture is teared down.
+    // --------------------------------------------------------
+
+    // (Default) Dead-letter any lingering messages on all the topic subscriptions.
+    options.OnTeardown.DeadLetterMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnTeardown.DeadLetterMessages(TimeSpan.FromSeconds(10));
+    options.OnTeardown.DeadLetterMessages((ServiceBusReceivedMessage msg) => 
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>");
+    });
+
+    // Complete any lingering messages on all the topic subscriptions.
+    options.OnTeardown.CompleteMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnTeardown.CompleteMessages(TimeSpan.FromSeconds(10));
+    options.OnTeardown.CompleteMessages((ServiceBusReceivedMessage msg) =>
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>"); 
+    });
+});
+```
+
+### Peek for messages
+The `TemporaryTopic` is equipped with a message filtering system that allows testers to search for messages during the lifetime of the test fixture. This can be useful to verify the current state of a topic, or as a test assertion to verify Service bus-related implementations.
+
+```csharp
+using Arcus.Testing;
+
+await using TemporaryTopic topic = ...
+
+IEnumerable<ServiceBusReceivedMessage> messages =
+  await topic.MessagesOn("<subscription-name>")
+
+              // Get subset messages currently on the topic subscription.
+             .Where(msg => msg.ApplicationProperties.ContainsKey("<my-key>"))
+             .Where(msg => msg.ContentType == "application/json")
+
+              // Get messages only from the dead-letter sub-queue.
+             .FromDeadLetter()
+
+             // Get only a number of messages (default: 100).
+             .Take(10)
+
+             // Start peeking for messages.
+             .ToListAsync();
+```
+
+</TabItem>
+<TabItem value="queue" label="Queue">
+
+## Temporary queue
+The `TemporaryQueue` provides a solution when the integration test requires an Azure Service Bus queue during the test run. A queue is created upon the setup of the test fixture and is deleted again when the test fixture is disposed.
+
+> ✨ Only when the test fixture was responsible for creating the queue, will the queue be deleted upon the fixture's disposal. This follows the 'clean environment' testing principle that describes that after the test run, the same state should be achieved as before the test run.
+
+```csharp
+using Arcus.Testing;
+
+await using var queue = await TemporaryQueue.CreateIfNotExistsAsync(
+  "<fully-qualified-namespace>", "<queue-name>", logger);
+```
+
+> ⚡ Uses by default the [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential) but other type of authentication mechanisms are supported with overloads.
+
+
+### Customization
+The `TemporaryQueue` allows testers to configure setup/teardown operations on any messages that were on the queue (or the queue itself) at the time of setup/teardown. This follows the 'clean environment' testing principle.
+
+```csharp
+using Arcus.Testing;
+
+await TemporaryQueue.CreateIfNotExistsAsync(..., options =>
+{
+    // Options related to when the test fixture is set up.
+    // ---------------------------------------------------
+
+    // Change the default queue-creation behavior.
+    options.OnSetup.CreateQueueWith((CreateQueueOptions opt) => ...);
+
+    // (Default) leave any existing messages on the queue. 
+    options.OnSetup.LeaveExistingMessages();
+
+    // Dead-letter any existing messages on the queue.
+    options.OnSetup.DeadLetterMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnSetup.DeadLetterMessages(TimeSpan.FromSeconds(10));
+    options.OnSetup.DeadLetterMessages((ServiceBusReceivedMessage msg) => 
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>");
+    });
+
+    // Complete any existing messages on the queue.
+    options.OnSetup.CompleteMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnSetup.CompleteMessages(TimeSpan.FromSeconds(10));
+    options.OnSetup.CompleteMessages((ServiceBusReceivedMessage msg) =>
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>"); 
+    });
+
+    // Options related to when the test fixture is teared down.
+    // --------------------------------------------------------
+
+    // (Default) Dead-letter any lingering messages on the queue.
+    options.OnTeardown.DeadLetterMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnTeardown.DeadLetterMessages(TimeSpan.FromSeconds(10));
+    options.OnTeardown.DeadLetterMessages((ServiceBusReceivedMessage msg) => 
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>");
+    });
+
+    // Complete any lingering messages on the queue.
+    options.OnTeardown.CompleteMessages(); // 💡 Max wait time default 5 seconds.
+    options.OnTeardown.CompleteMessages(TimeSpan.FromSeconds(10));
+    options.OnTeardown.CompleteMessages((ServiceBusReceivedMessage msg) =>
+    {
+        // ⚡ Multiple calls will be aggregated.
+        // ⚡ Can be used in combination with other complete/dead-letter operations.  
+        return msg.ApplicationProperties.ContainsKey("<key>"); 
+    });
+});
+```
+
+### Peek for messages
+The `TemporaryQueue` is equipped with a message filtering system that allows testers to search for messages during the lifetime of the test fixture. This can be useful to verify the current state of a queue, or as a test assertion to verify Service bus-related implementations.
+
+```csharp
+using Arcus.Testing;
+
+await using TemporaryQueue queue = ...
+
+IEnumerable<ServiceBusReceivedMessage> messages =
+  await queue.Messages
+
+              // Get subset messages currently on the queue.
+             .Where(msg => msg.ApplicationProperties.ContainsKey("<my-key>"))
+             .Where(msg => msg.ContentType == "application/json")
+
+              // Get messages only from the dead-letter sub-queue.
+             .FromDeadLetter()
+
+             // Get only a number of messages (default: 100).
+             .Take(10)
+
+             // Start peeking for messages.
+             .ToListAsync();
+```
+
+</TabItem>
+</Tabs>