From 17e56ebc3f3bc26f1be8bb00fc2ca7374c7aac15 Mon Sep 17 00:00:00 2001 From: confusingboat Date: Sat, 27 May 2023 20:10:14 -0500 Subject: [PATCH 1/5] update readme --- README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 657810c..0ec3525 100644 --- a/README.md +++ b/README.md @@ -1 +1,53 @@ -# ephemeral-db \ No newline at end of file +# Ephemeral + +## Create and automatically cleanup temporary external resources + +Infinitely extensible by design. Just install the packages for the types of resources you'd like to exist ephemerally. + +## The Convention +All primary integration points are provided in the main `Ephemeral` namespace, typically as extension methods. + +## Example Usage +To create a temporary Cosmos database and container for your persistence unit tests: +1. Install the relevant package: +``` +dotnet add package Ephemeral.Azure.Cosmos +``` +2. Import the namespace +```csharp +using Ephemeral; +``` +3. Create and use your resources +```csharp +[Test] +public async Task Test_should_pass() +{ + // Create the client to connect to the emulator (or any other instance) + var client = new CosmosClient( + "https://localhost:8081", + "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="); + + // Create the accessor, which is what manages the resource lifecycle + await using var databaseAccessor = client.CreateEphemeralDatabaseAccessor(); + + // Get an instance of the new database + // (creation actually happens here) + var db = await databaseAccessor.GetAsync(); + + // Now let's create the container + await using var containerAccessor = db.CreateEphemeralContainerAccessor(); + + // Get the instance of the container + var container = await containerAccessor.GetAsync(); + + // Do whatever you want here + + // Resources will be automatically cleaned up + // as we exit the using scopes +} +``` + +## Available Packages + +### `Ephemeral` +The core library with the main types. This will be included automatically as a dependency \ No newline at end of file From 842a4bd7f48c1d7aeaf09e98dc08318a64f919c9 Mon Sep 17 00:00:00 2001 From: confusingboat Date: Thu, 1 Jun 2023 00:45:49 -0500 Subject: [PATCH 2/5] update readme --- README.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 0ec3525..724271a 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ -# Ephemeral +# Ephemerally ## Create and automatically cleanup temporary external resources -Infinitely extensible by design. Just install the packages for the types of resources you'd like to exist ephemerally. +Infinitely extensible by design. Just install the packages for the types of resources you'd like to exist ephemerally (or create your own!). ## The Convention -All primary integration points are provided in the main `Ephemeral` namespace, typically as extension methods. +All primary integration points are provided in the main `Ephemerally` namespace, typically as extension methods. ## Example Usage To create a temporary Cosmos database and container for your persistence unit tests: 1. Install the relevant package: ``` -dotnet add package Ephemeral.Azure.Cosmos +dotnet add package Ephemerally.Azure.Cosmos ``` 2. Import the namespace ```csharp -using Ephemeral; +using Ephemerally; ``` 3. Create and use your resources ```csharp @@ -27,27 +27,29 @@ public async Task Test_should_pass() "https://localhost:8081", "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="); - // Create the accessor, which is what manages the resource lifecycle - await using var databaseAccessor = client.CreateEphemeralDatabaseAccessor(); + // Create a database + await using var database = await client.CreateEphemeralDatabaseAsync(); - // Get an instance of the new database - // (creation actually happens here) - var db = await databaseAccessor.GetAsync(); + // Now let's create a container + await using var container = await database.CreateEphemeralContainerAccessor(); - // Now let's create the container - await using var containerAccessor = db.CreateEphemeralContainerAccessor(); - - // Get the instance of the container - var container = await containerAccessor.GetAsync(); - - // Do whatever you want here + // You can even bring your own database or container to clean up automatically + database.GetContainer("myCoolContainer").ToEphemeral(); // Resources will be automatically cleaned up // as we exit the using scopes + + Assert.Pass(); } ``` ## Available Packages -### `Ephemeral` -The core library with the main types. This will be included automatically as a dependency \ No newline at end of file +### `Ephemerally` +The core library with the main types. This will be included automatically as a dependency. + +### `Ephemerally.Azure` +Placeholder for now to hold general Azure dependencies. + +### `Ephemerally.Azure.Cosmos` +Contains types and extension methods for creating and using ephemeral Cosmos DB resources. \ No newline at end of file From c745e45a405e85f7061076389b297d3045c0e016 Mon Sep 17 00:00:00 2001 From: Colton Fussy <519596+Confusingboat@users.noreply.github.com> Date: Fri, 2 Jun 2023 10:17:48 -0500 Subject: [PATCH 3/5] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 724271a..51bcbbd 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ public async Task Test_should_pass() await using var database = await client.CreateEphemeralDatabaseAsync(); // Now let's create a container - await using var container = await database.CreateEphemeralContainerAccessor(); + await using var container = await database.CreateEphemeralContainerAsync(); // You can even bring your own database or container to clean up automatically database.GetContainer("myCoolContainer").ToEphemeral(); @@ -52,4 +52,4 @@ The core library with the main types. This will be included automatically as a d Placeholder for now to hold general Azure dependencies. ### `Ephemerally.Azure.Cosmos` -Contains types and extension methods for creating and using ephemeral Cosmos DB resources. \ No newline at end of file +Contains types and extension methods for creating and using ephemeral Cosmos DB resources. From 07ca59527d6117d99d0636a6798f0eda78e54cb4 Mon Sep 17 00:00:00 2001 From: Colton Fussy <519596+Confusingboat@users.noreply.github.com> Date: Fri, 2 Jun 2023 10:20:20 -0500 Subject: [PATCH 4/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 51bcbbd..269eb45 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ public async Task Test_should_pass() await using var container = await database.CreateEphemeralContainerAsync(); // You can even bring your own database or container to clean up automatically - database.GetContainer("myCoolContainer").ToEphemeral(); + await using var myCoolContainer = database.GetContainer("myCoolContainer").ToEphemeral(); // Resources will be automatically cleaned up // as we exit the using scopes From 7654cc2d0ca219ea7301b361461650ef85117c6c Mon Sep 17 00:00:00 2001 From: confusingboat Date: Fri, 4 Jul 2025 12:06:19 -0500 Subject: [PATCH 5/5] update readme --- README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 269eb45..c48ab73 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,39 @@ -# Ephemerally +# Ephemerally + +![NuGet Downloads](https://img.shields.io/nuget/dt/Ephemerally) +![NuGet Version](https://img.shields.io/nuget/vpre/Ephemerally) + +### Packages available on [nuget.org](https://www.nuget.org/packages?q=Ephemerally) + +### Full documentation available in [the wiki](../../wiki) ## Create and automatically cleanup temporary external resources -Infinitely extensible by design. Just install the packages for the types of resources you'd like to exist ephemerally (or create your own!). +#### Extensible by design. Just install the appropriate package and start using resources ephemerally. + +## Why use this instead of `testcontainers`? + +Creating and tearing down entire containers per-test can be time-intensive and slow things down considerably, and not providing proper isolation can have other unintended side effects like race conditions or contamination of your test results. + +The best use cases will combine both approaches, using `testcontainers` to provide the infrastructure for the ephemeral resources created by `Ephemerally`, for example using `testcontainers` to provide a Redis instance for the `PooledEphemeralRedisMultiplexerFixture`. + +There are also use cases where it is not possible to use temporary containers with something like `testcontainers`, for example when: +- there is no containerized version of a resource +- policy forbids it +- technical challenges make it impractical +- there is a specific case like performance testing, where you want or need an actual, full-scale resource + +## Can I only use this in tests? -## The Convention -All primary integration points are provided in the main `Ephemerally` namespace, typically as extension methods. +While the primary use case is intended to be for testing, the projects are organized to allow the core functionality to be used anywhere without dependence on a test framework. +This is why the test-specific code is organized into separate projects like `Ephemerally.Azure.Cosmos.Xunit`. For example, if you would like to use ephemeral databases or containers for Cosmos in production code, you would only add `Ephemerally.Azure.Cosmos`. -## Example Usage +## Integration +Basic integration points are provided in the main `Ephemerally` namespace, typically as extension methods. + +Test fixtures will be under their respective package names (e.g. `Ephemerally.Azure.Cosmos.Xunit`). + +## Create Resources Ephemerally To create a temporary Cosmos database and container for your persistence unit tests: 1. Install the relevant package: ``` @@ -43,13 +69,61 @@ public async Task Test_should_pass() } ``` +## Test Fixtures +To utilize the premade fixtures (currently only available for xUnit): +1. Install the appropriate package: +``` +dotnet add package Ephemerally.Azure.Cosmos.Xunit +``` +2. Import the namespace +```csharp +using Ephemerally.Azure.Cosmos.Xunit; +``` +3. Add a fixture to your test class +```csharp +using Ephemerally.Azure.Cosmos.Xunit; +using Xunit; + +public class DatabaseFixtureUsageExampleTests(EphemeralCosmosDatabaseFixture fixture) + : IClassFixture +{ + // TODO: Tests go here +} +``` +4. Use the fixture +```csharp +using Ephemerally; +using Ephemerally.Azure.Cosmos.Xunit; +using Xunit; + +public class DatabaseFixtureUsageExampleTests(EphemeralCosmosDatabaseFixture fixture) + : IClassFixture +{ + [Fact] + public async Task TestUsingDatabase() + { + // Ephemeral databases go well with ephemeral containers to keep tests isolated + await using var container = await fixture.Database.CreateEphemeralContainerAsync(); + } +} +``` + ## Available Packages ### `Ephemerally` -The core library with the main types. This will be included automatically as a dependency. +Base package with shared types. This will be included automatically as a transitive dependency. ### `Ephemerally.Azure` Placeholder for now to hold general Azure dependencies. ### `Ephemerally.Azure.Cosmos` Contains types and extension methods for creating and using ephemeral Cosmos DB resources. + +### `Ephemerally.Azure.Cosmos.Xunit` +xUnit fixtures for simplifying test integration with `Ephemerally.Azure.Cosmos` + +### `Ephemerally.Redis` +Classes and methods for creating and managing the lifecycle of ephemeral Redis resources + +### `Ephemerally.Redis.Xunit` +xUnit fixtures for simplifying test integration with `Ephemerally.Redis` \ No newline at end of file