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
The following functionality is available when installing this package:
PM> Install-Package -Name Arcus.Testing.Storage.Cosmos
- MongoDb
- NoSql
🛡️ Make sure that the test client that interacts with the Cosmos storage has at least
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.
⚡ The test fixture automatically uses an existing collection - if exists, but does not remove it if it was not responsible for creating the collection.
using Arcus.Testing;
ResourceIdentifier cosmosDbAccountResourceId = ...
await using var collection = await TemporaryMongoDbCollection.CreateIfNotExistsAsync(
cosmosDbAccountResourceId,
"<database-name>",
"<collection-name>",
logger);
// Interact with the collection during the lifetime of the fixture.
IMongoCollection<Shipment> client = collection.GetCollectionClient<Shipment>();
🎖️ Overloads are available that takes in the
IMongoDatabase
for custom authentication mechanisms. By default, it uses theDefaultAzureCredential
.
Inserting documents in the collection can also be done via the test fixture. It always make sure that any inserted documents are removed afterwards.
using Arcus.Testing;
await using TemporaryMongoDbCollection collection = ...
await collection.InsertDocumentAsync(new Shipment { BoatName = "The Alice" });
Customization
The setup and teardown process of the temporary collection is configurable. By default, it always removes any resources that it was responsible for creating.
using Arcus.Testing;
await TemporaryMongoDbCollection.CreateIfNotExistsAsync(..., options =>
{
// Options related to when the test fixture is set up.
// ---------------------------------------------------
// (Default) Leaves all existing MongoDb documents untouched when the test fixture is created.
options.OnSetup.LeaveAllDocuments();
// Delete all MongoDb documents that already existed before the test fixture creation, when there was already a MongoDb collection available.
options.OnSetup.CleanAllDocuments();
// Delete all MongoDb documents that matches any of the configured filters,
// upon the test fixture creation, when there was already a MongoDb collection available.
options.OnSetup.CleanMatchingDocuments(
Builders<Shipment>.Filter.Eq(s => s.BoatName, "The Alice"));
options.OnSetup.CleanMatchingDocuments((Shipment s) => s.BoatName == "The Alice");
// Options related to when the test fixture is teared down.
// --------------------------------------------------------
// (Default) Delete all MongoDb documents that were inserted by the test fixture.
options.OnTeardown.CleanCreatedDocuments();
// Delete all MongoDb documents upon the test fixture disposal,
// even if the test fixture didn't inserted them.
options.OnTeardown.CleanAllDocuments();
// Delete all MongoDb documents that matches any of the configured filters,
// upon the test fixture disposal, even if the test fixture didn't inserted them.
// ⚠️ MongoDb documents inserted by the test fixture will always be deleted, regardless of the configured filters.
options.OnTeardown.CleanMatchingDocuments(
Builders<Shipment>.Filter.Eq(s => s.BoatName, "The Alice"));
options.OnTeardown.CleanMatchingDocuments((Shipment s) => s.BoatName == "The Alice");
});
// `OnTeardown` is also still available after the temporary collection is created:
await using TemporaryMongoDbCollection collection = ...
collection.OnTeardown.CleanAllDocuments();
🎖️ The
TemporaryMongoDbCollection
will always remove any MongoDb documents that were inserted via the temporary collection itself with thecollection.InsertDocumentAsync
. This follows the 'clean environment' testing principal that any test should not leave any state it created behind after the test has run.
Temporary MongoDb document
The TemporaryMongoDbDocument
provides a solution when the integration test requires a document during the test run. A MongoDb document is created upon the setup of the test fixture and is deleted again when the test fixture is disposed.
When the document already existed (already a document with a same configured document ID), then the test fixture will revert to the original content of the document upon the test fixture disposal.
⚡ Whether or not the test fixture should use an existing document is set by using an existing document ID (
_id
by default).
using Arcus.Testing;
ResourceIdentifier cosmosDbAccountResourceId = ...
var shipment = new Shipment { BoatName = "The Alice" };
await using var document = await TemporaryMongoDbDocument.InsertIfNotExistsAsync(
cosmosDbAccountResourceId,
"<database-name>",
"<collection-name>",
shipment,
logger);
BsonValue documentId = document.Id;
🛡️ Make sure that the test client that interacts with the Cosmos storage has at least
Cosmos DB Built-in Data Contributor
-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:
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.
⚡ The test fixture automatically uses an existing container - if exists, but does not remove it if it was not responsible for creating the container.
using Arcus.Testing;
ResourceIdentifier cosmosDbAccountResourceId = ...
await using var container = await TemporaryNoSqlContainer.CreateIfNotExistsAsync(
cosmosDbAccountResourceId,
"<database-name>",
"<container-name>",
"/partition-key-path",
logger);
// Interact with the container during the lifetime of the fixture.
Container client = container.Client;
🎖️ Overloads are available for custom authentication mechanisms. By default, it uses the
DefaultAzureCredential
.
Inserting items in the container can also be done via the test fixture. It always make sure that any inserted items are removed afterwards.
using Arcus.Testing;
await using TemporaryNoSqlContainer container = ...
await container.AddItemAsync(new Shipment { Id = "123", BoatName = "The Alice" });
Customization
The setup and teardown process of the temporary container is configurable. By default, it always removes any resources that it was responsible for creating.
using Arcus.Testing;
await TemporaryNoSqlContainer.CreateIfNotExistsAsync(..., options =>
{
// Options related to when the test fixture is set up.
// ---------------------------------------------------
// (Default) Leaves all existing NoSql items untouched when the test fixture is created.
options.OnSetup.LeaveAllItems();
// Delete all NoSql items that already existed before the test fixture creation, when there was already a NoSql container available.
options.OnSetup.CleanAllItems();
// Delete all NoSql items that matches any of the configured filters,
// upon the test fixture creation, when there was already a NoSql container available.
options.OnSetup.CleanMatchingItems(
NoSqlItemFilter.Where(ship => ship["BoatName"] == "The Alice"),
NoSqlItemFilter.ItemIdEqual("123"));
// Options related to when the test fixture is teared down.
// --------------------------------------------------------
// (Default) Delete all NoSql items that were inserted by the test fixture.
options.OnTeardown.CleanCreatedItems();
// Delete all NoSql items upon the test fixture disposal,
// even if the test fixture didn't inserted them.
options.OnTeardown.CleanAllItems();
// Delete all NoSql items that matches any of the configured filters,
// upon the test fixture disposal, even if the test fixture didn't inserted them.
// ⚠️ NoSql items inserted by the test fixture will always be deleted, regardless of the configured filters.
options.OnTeardown.CleanMatchingItems(
NoSqlItemFilter.Where((Shipment s) => s.BoatName == "The Alice"),
NoSqlItemFilter.IdEqual("123"));
});
// `OnTeardown` is also still available after the temporary container is created:
await using TemporaryNoSqlContainer container = ...
container.OnTeardown.CleanAllItems();
🎖️ The
TemporaryNoSqlContainer
will always remove any NoSql items that were inserted via the temporary container itself with thecontainer.AddItemAsync
. This follows the 'clean environment' testing principal that any test should not leave any state it created behind after the test has run.
Temporary NoSql item
The TemporaryNoSqlItem
provides a solution when the integration test requires a item during the test run. A NoSql item is created upon the setup of the test fixture and is deleted again when the test fixture is disposed.
⚡ When the item already existed (already a item with a same configured item ID), then the test fixture will revert to the original content of the item upon the test fixture disposal.
using Arcus.Testing;
Container containerClient = ...
var shipment = new Shipment { Id = "123", BoatName = "The Alice" };
await using var item = await TemporaryNoSqlItem.InsertIfNotExistsAsync(
containerClient,
shipment,
logger);
string itemId = item.Id;
PartitionKey partitionKey = item.PartitionKey;