Skip to main content
Version: v1.1.0

Migrate your test suite from Testing Framework to Arcus.Testing v1.0

This guide will walk you through the process of migrating your test suite from using the Testing Framework to Arcus.Testing.

⚠️ IMPORTANT to note that the Arcus.Testing approach uses the files in the build output in any of its functionality (TestConfig, ResourceDirectory...). It uses this approach for more easily access to the actual files used (instead of hidden as an embedded resource). It is best to add your files needed in your test project either as links (see how) or as actual files if only used for testing. In both cases, they need to be copied to the output.:

<ItemGroup>
  <None Update="resource.xml">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>

Replace Codit.Testing.OutputComparison/Xslt with Arcus.Testing.Assert​

The Codit.Testing.OutputComparison library has some functionality to compare different kinds of file types. The new Arcus.Testing.Assert library handles these comparisons from now on.

Start by installing this library:

PM > Install-Package -Name Arcus.Testing.Assert

🔗 See the feature documentation for more info on the supported assertions.

🔗 See the code samples for fully-implemented examples on before/after with the Testing Framework.

You can use AssertXml like any other assertion method. Instead of returning a boolean and a message, it throws an exception with a detailed report in case of a difference.

- using Codit.Testing.OutputComparison;
+ using Arcus.Testing;

string expectedXml = ...;
string actualXml = ...;

- using Stream expectedXmlStream = ...;
- using Stream actualXmlStream = ...;
- bool isEqual = Xml.Compare(
-     actualXmlStream, expectedXmlStream, out string userMessage, nodesToIgnore: Array.Empty<string>());

+ AssertXml.Equal(expectedXml, actualXml);

Any nodes that should be ignored can be configured by passing additional options:

- using Codit.Testing.OutputComparison;
+ using Arcus.Testing;

- bool isEqual = Xml.Compare(..., new[] { "ignore-this-node" });
+ AssertXml.Equal(..., options =>
+ {
+     options.AddIgnoreNode("ignore-this-node");
+ });

🔗 See the feature documentation for more info on the AssertXml.

XSLT​

Transforming XML-XML to XML-JSON now also happens in a test asserted manner. It does not use the file name anymore and a 'convention by configuration' file structure, but needs the actual contents. You can use the test-friendly ResourceDirectory in the Arcus.Testing.Core package to load the files.

⚠️ IMPORTANT that you add your XSLT files as links to the test project, that way any changes to the XSLT in the implementation project will be automatically copied to the XSLT transformation used in the tests.

Here's how XML-XML now works:

- using.Codit.Testing.Xslt;
+ using Arcus.Testing;

- // _input.xml file is loaded implicitly.
- // _expected.xml file is loaded implicitly.
- bool successfullyTransformed = XsltHelper.TestXslt(
-     "transformer.xslt",
-     out string userMessage,
-     xsltArgumentList: null,
-     MessageOutputType.Xml);

+ string inputXml = ... // Load _input.xml file explicitly.
+ string transformerXslt = ... // Load transformer.xslt file's contents here.

+ string actualXml = AssertXslt.TransformToXml(transformerXslt, inputXml);
+ // Use `AssertXml.Equal` to determine the difference next.

💡You can use the test-friendly AssertXml/Xslt.Load functionality to load raw contents to their respectful XSLT/XML document. Upon failure, a load exception with a detailed description will be reported to the tester.

💡 You can use the test-friendly ResourceDirectory functionality in the Arcus.Testing.Core package to load raw file contents. Upon failure, a not-found exception with a detailed description will be reported to the tester.

Sequential transformations​

The original Testing Framework had a TestXsltSequential exposed functionality to run multiple XSLT transformation in sequence (output of one transformation becomes input of another). This was using separate input types for file names. Since this is made explicit in the Arcus.Testing packages, you can load those files yourself using the ResourceDirectory type and do the sequential transformation in a more explicit manner:

- using Codit.Testing.Xslt;
+ using Arcus.Testing;

- // XlstAndArgumentList[] xsltFileNames = ...
- bool success = XsltHelper.TestXsltSequential(xsltFileNames, out string message);

+ string[] xsltFileContents = ...
+ string inputContent = ...
+ string output = xsltFileContents.Aggregate(inputContent, (xslt, xml) => AssertXslt.TransformToXml(xslt, xml));

Replace Codit.Testing.DataFactory with Arcus.Testing.Integration.DataFactory​

The Codit.Testing.DataFactory handled start/stop functionality on DataFlow/Pipelines in DataFactory with and without debug sessions. Testing DataFlow's and managing debug sessions is now fully managed with Arcus.Testing.Integration.DataFactory.

Start by installing this library:

PM > Install-Package -Name Arcus.Testing.Integration.DataFactory

Start a debug session​

Arcus wraps the start/stop functionality previously defined in the testing framework as a single temporary test fixture that can act as a singleton test fixture for your entire test suite.

- using Codit.Testing.DataFactory;
+ using Arcus.Testing;

- string activeSessionId = await DataFactoryHelper.StartDataFlowAsync(
-     "<subscription-id>",
-     "<tenant-id>",
-     "<object-id>",
-     "<client-id>",
-     "<client-certificate>",
-     "<data-factory-name>",
-     "<data-factory-resource-group-name>",
-     "<data-flow-name>",
-     "<session-id>",
-     "<key-vault-linked-service>",
-     dataflowParameters: new Dictionary<string, object>(),
-     datasetParameters: new Dictionary<string, Dictionary<string, object>>(),
-     timeout: 30);

+ var resourceId =
+     DataFactoryResource.CreateResourceIdentifier("<subscription-id>", "<resource-group-name>", "<data-factory-name>");

+ await using var session =
+     await TemporaryDataFlowDebugSession.StartDebugSessionAsync(resourceId, logger);

Run a DataFlow in debug session​

Starting DataFlow's in a debug session is now linked to the TemporaryDataFlowDebugSession test fixture. A method is available to run a particular DataFlow, while expecting the result to become available in a passed-in sink.

- using Codit.Testing.DataFactory;
+ using Arcus.Testing;

- (bool isSuccess, string errorMessage) = 
-     await DataFactoryHelper.CheckDataFactoryDataFlowDebugOutputAsync(
-         "<subscription-id>",
-         "<tenant-id>",
-         "<client-id>",
-         "<client-certificate>",
-         "<data-factory-name>",
-         "<data-factory-resource-group-name>",
-         activeSessionId,
-         "<data-flow-name>",
-         "<data-flow-sink-name>",
-         expectedData: new List<Dictionary<string, object>>());

+ DataFlowRunResult result =
+     await session.RunDataFlowAsync("<data-flow-name>", "<data-flow-sink-name>", 
+         options =>
+         {
+             options.TimeToLiveInMinutes = 30;
+         });

+ JsonNode actual = result.GetDataAsJson();
+ JsonNode expected = // Load your expected JSON...
+ AssertJson.Equal(expected, actual);

⚡ Assertion is now separated also from the run operation. Arcus.Testing.Assert can be used to assert on the available sink result.

Run a Data pipeline​

Arcus does not provide any additional functionality to run a pipeline and wait for its result, as all this can be easily done with the Azure.ResourceManager.DataFactory and Arcus.Testing.Core packages.

🔗 See the feature documentation for more information on testing DataFactory functionality.

Replace Codit.Testing.BlobStorage with Arcus.Testing.Storage.Blob​

The Codit.Testing.BlobStorage in the past acted as a wrapper for common storage operations. The container/blob operations are now available as single test fixtures in the Arcus.Testing.Storage.Blob library.

These fixtures are configurable to fit the need of the test, instead of having to call multiple methods on 'helpers'.

Start by installing this library:

PM > Install-Package -Name Arcus.Testing.Storage.Blob

Interact with Blob container​

The testing framework separated storage operations, which are now collected in a single TemporaryBlobContainer test fixture. Based on the needs of the test, the fixture can be adapted. Interacting with the container can be done with the Azure SDK.

- using Codit.Testing.BlobStorage;
+ using Arcus.Testing.Storage.Blob;

- // Implicitly creates the container if it does not exists.
- BlobStorageHelper.ListBlobsAsync("<connection-string>", "<container-name>", "<prefix>");

+ // Container gets deleted if created by test, otherwise is left alone on disposal.
+ await using var container = await TemporaryBlobContainer.CreateIfNotExistsAsync(
+     "<account-name>",
+     "<container-name>",
+     logger);

+ BlobContainerClient client = container.Client;
+ await client.GetBlobsAsync(BlobTraits.None, BlobStates.None, "<prefix>");

🔗 See the feature documentation for more information on interacting with Blob storage.

Interact with Blob file​

The testing framework separated storage operations, which are now collected in a single TemporaryBlobFile test fixture. Based on the needs of the test, the fixture can be adapted. Interacting with the file can be done with the Azure SDK.

- using Codit.Testing.BlobStorage;
+ using Arcus.Testing.Storage.Blob;

- await BlobStorageHelper.UploadFileToBlobStorageAsync(
-     "<connection-string>", "<container-name>", "<source-file>", "<prefix>");

+ // File gets deleted if created by test, otherwise replaced with original on disposal. 
+ await using var fs = File.OpenRead("<source-file>");
+ await using var file = await TemporaryBlobFile.UploadIfNotExistsAsync(
+     new Uri("https://<account-name>.blob.core.windows.net/<container-name>"),
+     "prefix/<blob-name>",
+     BinaryData.FromStream(fs),
+     logger);

+ BlobClient = file.Client;

🔗 See the feature documentation for more information on interacting with Blob storage.