Unit testing and mocking

docs/azure/TOC.yml

@@ -61,6 +61,8 @@
       href: ./sdk/logging.md
     - name: Pagination
       href: ./sdk/pagination.md
+    - name: Unit testing and mocking
+      href: ./sdk/unit-testing-mocking.md
     - name: Configure a proxy server
       href: ./sdk/azure-sdk-configure-proxy.md
     - name: Packages list

docs/azure/sdk/snippets/unit-testing/AboutToExpireSecretsFinder.cs

@@ -0,0 +1,29 @@
+using Azure.Security.KeyVault.Secrets;
+
+public class AboutToExpireSecretFinder
+{
+    private readonly TimeSpan _threshold;
+    private readonly SecretClient _client;
+
+    public AboutToExpireSecretFinder(TimeSpan threshold, SecretClient client)
+    {
+        _threshold = threshold;
+        _client = client;
+    }
+
+    public async Task<string[]> GetAboutToExpireSecretsAsync()
+    {
+        List<string> secretsAboutToExpire = new();
+
+        await foreach (var secret in _client.GetPropertiesOfSecretsAsync())
+        {
+            if (secret.ExpiresOn.HasValue &&
+                secret.ExpiresOn.Value - DateTimeOffset.Now <= _threshold)
+            {
+                secretsAboutToExpire.Add(secret.Name);
+            }
+        }
+
+        return secretsAboutToExpire.ToArray();
+    }
+}

docs/azure/sdk/snippets/unit-testing/Moq/AboutToExpireSecretsFinderTests_Moq.cs

@@ -0,0 +1,71 @@
+using Azure;
+using Azure.Security.KeyVault.Secrets;
+using Moq;
+
+namespace UnitTestingSampleApp.Moq;
+
+public class AboutToExpireSecretFinderTests_Moq
+{
+    [Fact]
+    public async Task DoesNotReturnNonExpiringSecrets()
+    {
+        // Arrange
+        // Create a page of enumeration results
+        Page<SecretProperties> page = Page<SecretProperties>.FromValues(new[]
+        {
+            new SecretProperties("secret1") { ExpiresOn = null },
+            new SecretProperties("secret2") { ExpiresOn = null }
+        }, null, Mock.Of<Response>());
+
+        // Create a pageable that consists of a single page
+        AsyncPageable<SecretProperties> pageable =
+            AsyncPageable<SecretProperties>.FromPages(new[] { page });
+
+        // Setup a client mock object to return the pageable
+        var clientMock = new Mock<SecretClient>();
+        clientMock.Setup(c => c.GetPropertiesOfSecretsAsync(It.IsAny<CancellationToken>()))
+            .Returns(pageable);
+
+        // Create an instance of a class to test passing in the mock client
+        var finder = new AboutToExpireSecretFinder(TimeSpan.FromDays(2), clientMock.Object);
+
+        // Act
+        string[] soonToExpire = await finder.GetAboutToExpireSecretsAsync();
+
+        // Assert
+        Assert.Empty(soonToExpire);
+    }
+
+    [Fact]
+    public async Task ReturnsSecretsThatExpireSoon()
+    {
+        // Arrange
+
+        // Create a page of enumeration results
+        DateTimeOffset now = DateTimeOffset.Now;
+        Page<SecretProperties> page = Page<SecretProperties>.FromValues(new[]
+        {
+            new SecretProperties("secret1") { ExpiresOn = now.AddDays(1) },
+            new SecretProperties("secret2") { ExpiresOn = now.AddDays(2) },
+            new SecretProperties("secret3") { ExpiresOn = now.AddDays(3) }
+        }, null, Mock.Of<Response>());
+
+        // Create a pageable that consists of a single page
+        AsyncPageable<SecretProperties> pageable =
+            AsyncPageable<SecretProperties>.FromPages(new[] { page });
+
+        // Setup a client mock object to return the pageable
+        var clientMock = new Mock<SecretClient>();
+        clientMock.Setup(c => c.GetPropertiesOfSecretsAsync(It.IsAny<CancellationToken>()))
+            .Returns(pageable);
+
+        // Create an instance of a class to test passing in the mock client
+        var finder = new AboutToExpireSecretFinder(TimeSpan.FromDays(2), clientMock.Object);
+
+        // Act
+        string[] soonToExpire = await finder.GetAboutToExpireSecretsAsync();
+
+        // Assert
+        Assert.Equal(new[] { "secret1", "secret2" }, soonToExpire);
+    }
+}

docs/azure/sdk/snippets/unit-testing/Moq/TestSnippets_Moq.cs

@@ -0,0 +1,100 @@
+using Azure.Security.KeyVault.Secrets;
+using Azure;
+using Moq;
+
+namespace UnitTestingSampleApp.Moq;
+
+public class TestSnippets_Moq
+{
+    public void ServiceClientSnippets()
+    {
+        // <MockSecretClient>
+        KeyVaultSecret keyVaultSecret = SecretModelFactory.KeyVaultSecret(
+            new SecretProperties("secret"), "secretValue");
+
+        Mock<SecretClient> clientMock = new Mock<SecretClient>();
+        clientMock.Setup(c => c.GetSecret(
+                It.IsAny<string>(),
+                It.IsAny<string>(),
+                It.IsAny<CancellationToken>())
+            )
+            .Returns(Response.FromValue(keyVaultSecret, Mock.Of<Response>()));
+
+        clientMock.Setup(c => c.GetSecretAsync(
+                It.IsAny<string>(),
+                It.IsAny<string>(),
+                It.IsAny<CancellationToken>())
+            )
+            .ReturnsAsync(Response.FromValue(keyVaultSecret, Mock.Of<Response>()));
+
+        SecretClient secretClient = clientMock.Object;
+        // </MockSecretClient>
+    }
+
+    public void ResponseTypeSnippets()
+    {
+        // <MockResponse>
+        Mock<Response> responseMock = new Mock<Response>();
+        responseMock.SetupGet(r => r.Status).Returns(200);
+
+        Response response = responseMock.Object;
+        // </MockResponse>
+    }
+
+    public void ResponseTypeTSnippets()
+    {
+        // <MockResponseT>
+        KeyVaultSecret keyVaultSecret = SecretModelFactory.KeyVaultSecret(
+            new SecretProperties("secret"), "secretValue");
+        Response<KeyVaultSecret> response = Response.FromValue(keyVaultSecret, Mock.Of<Response>());
+        // </MockResponseT>
+    }
+
+    public void PaggingSnippets()
+    {
+        // <SingleResponsePage>
+        Page<SecretProperties> responsePage = Page<SecretProperties>.FromValues(
+            new[] {
+                new SecretProperties("secret1"),
+                new SecretProperties("secret2")
+            },
+            continuationToken: null,
+            Mock.Of<Response>());
+        // </SingleResponsePage>
+
+        // <MultipleResponsePage>
+        Page<SecretProperties> page1 = Page<SecretProperties>.FromValues(
+            new[]
+            {
+                new SecretProperties("secret1"),
+                new SecretProperties("secret2")
+            },
+            "continuationToken",
+            Mock.Of<Response>());
+
+        Page<SecretProperties> page2 = Page<SecretProperties>.FromValues(
+            new[]
+            {
+                new SecretProperties("secret3"),
+                new SecretProperties("secret4")
+            },
+            "continuationToken2",
+            Mock.Of<Response>());
+
+        Page<SecretProperties> lastPage = Page<SecretProperties>.FromValues(
+            new[]
+            {
+                new SecretProperties("secret5"),
+                new SecretProperties("secret6")
+            },
+            continuationToken: null,
+            Mock.Of<Response>());
+
+        Pageable<SecretProperties> pageable = Pageable<SecretProperties>
+            .FromPages(new[] { page1, page2, lastPage });
+
+        AsyncPageable<SecretProperties> asyncPageable = AsyncPageable<SecretProperties>
+            .FromPages(new[] { page1, page2, lastPage });
+        // </MultipleResponsePage>
+    }
+}

docs/azure/sdk/snippets/unit-testing/NSubstitute/AboutToExpireSecretsFinderTests_NSubstitute.cs

@@ -0,0 +1,71 @@
+using Azure;
+using Azure.Security.KeyVault.Secrets;
+using NSubstitute;
+
+namespace UnitTestingSampleApp.NSubstitute;
+
+public class AboutToExpireSecretFinderTests_NSubstitute
+{
+    [Fact]
+    public async Task DoesNotReturnNonExpiringSecrets()
+    {
+        // Arrange
+        // Create a page of enumeration results
+        Page<SecretProperties> page = Page<SecretProperties>.FromValues(new[]
+        {
+            new SecretProperties("secret1") { ExpiresOn = null },
+            new SecretProperties("secret2") { ExpiresOn = null }
+        }, null, Substitute.For<Response>());
+
+        // Create a pageable that consists of a single page
+        AsyncPageable<SecretProperties> pageable =
+            AsyncPageable<SecretProperties>.FromPages(new[] { page });
+
+        // Setup a client mock object to return the pageable
+        SecretClient clientMock = Substitute.For<SecretClient>();
+        clientMock.GetPropertiesOfSecretsAsync(Arg.Any<CancellationToken>())
+            .Returns(pageable);
+
+        // Create an instance of a class to test passing in the mock client
+        var finder = new AboutToExpireSecretFinder(TimeSpan.FromDays(2), clientMock);
+
+        // Act
+        var soonToExpire = await finder.GetAboutToExpireSecretsAsync();
+
+        // Assert
+        Assert.Empty(soonToExpire);
+    }
+
+    [Fact]
+    public async Task ReturnsSecretsThatExpireSoon()
+    {
+        // Arrange
+
+        // Create a page of enumeration results
+        DateTimeOffset now = DateTimeOffset.Now;
+        Page<SecretProperties> page = Page<SecretProperties>.FromValues(new[]
+        {
+            new SecretProperties("secret1") { ExpiresOn = now.AddDays(1) },
+            new SecretProperties("secret2") { ExpiresOn = now.AddDays(2) },
+            new SecretProperties("secret3") { ExpiresOn = now.AddDays(3) }
+        }, null,Substitute.For<Response>());
+
+        // Create a pageable that consists of a single page
+        AsyncPageable<SecretProperties> pageable =
+            AsyncPageable<SecretProperties>.FromPages(new[] { page });
+
+        // Setup a client mock object to return the pageable
+        SecretClient clientMock = Substitute.For<SecretClient>();
+        clientMock.GetPropertiesOfSecretsAsync(Arg.Any<CancellationToken>())
+            .Returns(pageable);
+
+        // Create an instance of a class to test passing in the mock client
+        var finder = new AboutToExpireSecretFinder(TimeSpan.FromDays(2), clientMock);
+
+        // Act
+        var soonToExpire = await finder.GetAboutToExpireSecretsAsync();
+
+        // Assert
+        Assert.Equal(new[] { "secret1", "secret2" }, soonToExpire);
+    }
+}

docs/azure/sdk/snippets/unit-testing/NSubstitute/TestSnippets_NSubstitute.cs

@@ -0,0 +1,102 @@
+using Azure.Security.KeyVault.Secrets;
+using Azure;
+using NSubstitute;
+
+namespace UnitTestingSampleApp.NSubstitute;
+
+public class TestSnippets_NSubstitute
+{
+    public void ServiceClientSnippets()
+    {
+        // <MockSecretClient>
+        KeyVaultSecret keyVaultSecret = SecretModelFactory.KeyVaultSecret(
+            new SecretProperties("secret"), "secretValue");
+
+        SecretClient clientMock = Substitute.For<SecretClient>();
+        clientMock.GetSecret(
+                Arg.Any<string>(),
+                Arg.Any<string>(),
+                Arg.Any<CancellationToken>()
+            )
+            .Returns(Response.FromValue(keyVaultSecret, Substitute.For<Response>()));
+
+        clientMock.GetSecretAsync(
+                Arg.Any<string>(),
+                Arg.Any<string>(),
+                Arg.Any<CancellationToken>()
+            )
+            .Returns(Response.FromValue(keyVaultSecret, Substitute.For<Response>()));
+
+        SecretClient secretClient = clientMock;
+        // </MockSecretClient>
+    }
+
+    public void ResponseTypeSnippets()
+    {
+        // <MockResponse>
+        Response responseMock = Substitute.For<Response>();
+        responseMock.Status.Returns(200);
+
+        Response response = responseMock;
+        // </MockResponse>
+    }
+
+    public void ResponseTypeTSnippets()
+    {
+        // <MockResponseT>
+        KeyVaultSecret keyVaultSecret = SecretModelFactory.KeyVaultSecret(
+            new SecretProperties("secret"), "secretValue");
+        Response<KeyVaultSecret> response = Response.FromValue(keyVaultSecret, Substitute.For<Response>());
+        // </MockResponseT>
+    }
+
+
+    public void PaggingSnippets()
+    {
+        // <SingleResponsePage>
+        Page<SecretProperties> responsePage = Page<SecretProperties>.FromValues(
+            new[] {
+                new SecretProperties("secret1"),
+                new SecretProperties("secret2")
+            },
+            continuationToken: null,
+            Substitute.For<Response>());
+        // </SingleResponsePage>
+
+        // <MultipleResponsePage>
+        Page<SecretProperties> page1 = Page<SecretProperties>.FromValues(
+            new[]
+            {
+                new SecretProperties("secret1"),
+                new SecretProperties("secret2")
+            },
+            "continuationToken",
+            Substitute.For<Response>());
+
+        Page<SecretProperties> page2 = Page<SecretProperties>.FromValues(
+            new[]
+            {
+                new SecretProperties("secret3"),
+                new SecretProperties("secret4")
+            },
+            "continuationToken2",
+            Substitute.For<Response>());
+
+        Page<SecretProperties> lastPage = Page<SecretProperties>.FromValues(
+            new[]
+            {
+                new SecretProperties("secret5"),
+                new SecretProperties("secret6")
+            },
+            continuationToken: null,
+            Substitute.For<Response>());
+
+        Pageable<SecretProperties> pageable = Pageable<SecretProperties>
+            .FromPages(new[] { page1, page2, lastPage });
+
+        AsyncPageable<SecretProperties> asyncPageable = AsyncPageable<SecretProperties>
+            .FromPages(new[] { page1, page2, lastPage });
+        // </MultipleResponsePage>
+    }
+
+}