After a great weekend at SoCalCodeCamp San Diego, I came home “super excited”. After a good night’s sleep I got cracking first thing in the morning, the result is CompositionTests v1.2.0.
Thanks to github:pages the project has a pretty new home page at compositiontests.com. You can head over there to check out the source. If you just want the bits, they’re waiting for you on NuGet.org.
Read on to find out what’s new.
Built-in Scrubbers Handle Nulls Properly
Since scrubbers are called one after the other, its possible for one scrubber to nullify the entire string and pass it to the next. The built in scrubbers all check for null and simply pass the value through without processing when one is encountered. Custom scrubbers that don’t follow the same design risk a NullReferenceException at runtime.
Normalized Line Endings and Indentation
For some reason the (newer) exception messages generated by MEF use LF instead of CRLF when describing the contract name of the missing part. This creates a usability issue when viewing the approved or received files in Visual Studio because Visual Studio displays a modal dialog that will offer to normalize the line endings for you. But, if you normalize the line endings and approve, then you will never get a matching received file because the exceptions will not be normalized. If you choose not to normalize the line endings in order to ensure consistency between the received and approved files, you will have to dismiss Visual Studio’s offer every time you open the file.
So, to make life easy, CompositionTests will normalize the line endings before sending the formatted text to ApprovalTests.
Likewise, the exception messages use tabs, while the CompositionInfoTextFormatter uses spaces. Certain Visual Studio extensions will offer to normalize this for you. On my system, this is not nearly annoying as Visual Studio, because the offer is not made in a modal dialog box and I can just ignore it if I like. However, if someone were to normalize and approve the normalized file, they once again have broken consistency between the received and approved file. So, CompositionTests will replace tabs with spaces before sending the formatted text to ApprovalTests.
New API (Backward Compatible for Now)
I had a chance to sit down with Llewellyn Falco at SoCalCodeCamp, and we did some pairing on ApprovalTests and CompositionTests. We renamed the primary helper class from Composition to MefComposition since only MEF composition is supported.
We also created a specialized VerifyDirectoryCatalog method that automatically provides the scrubbers that make sense when working with a DirectoryCatalog. From this starting point I created additional Verify* methods for each of the four supported catalog types. The old DiscoverParts methods have been marked with the ObsoleteAttribute, along with the old Composition class.
MefComposition still supports the old API, but the methods have been renamed. You can find them by looking at the group of methods called VerifyCompositionInfo. These methods can directly replace your calls to DiscoverParts and they still allow you to pass in a custom ExportProvider, etc.
These changes are meant to be backward compatible in this release, so if I’ve inadvertently broken compatibility, that’s a bug, let me know. Please stop using DiscoverParts and Composition, they will be removed in a future release.
I find it awkward to work with the Write method provided by CompositionInfoTextFormatter. Since I’m now using OrderedCompositionInfoTextFormatter by default, I added a Format method that hides the parts I feel are awkward.
I’m trying to adopt semantic versioning. If I had adopted this system from the start, then I probably would not yet be at v1. I’m already there, so I’m just going to try my best to follow this convention from now on. Since I don’t want to go to v2 yet, I’ve tried to maintain backward compatibility with the old API, so this release puts us at v1.2.0.
To document the API, I’ve added an ApiApprover test. Like CompositionTests, ApiApprover leverages ApprovalTests to introduce a cool new testing scenario. The test discovers the public API, and will fail if the API changes. Since it uses ApprovalTests, the public API ends up documented in the .approved file for the API Approver test. So, you can find the public API listed out in “ApiTest.ApprovePublicApi.approved.txt” in the test folder.
Check It Out
Head over to the new homepage. I’ve updated the Readme with some nice examples that should help get you up to speed and testing quickly.