UnitTesting_with_Facts.md

Fact based unit tests

If you are familiar with fact based unit tests (as shown in Microsoft documentation) you can continue to use that approach with LibPQ UnitTest framework. Integrating existing fact based test suites will require some extra code, but the tests themselves need no modification.

NOTE: Authors believe that LibPQ UnitTest offers more features and has more stable API than fact based tests offered by Microsoft. We recommend writing new tests with native UnitTest approach and using fact based tests only to integrate pre-existing test code

Writing fact based unit tests

With fact based tests a test case is a fact generated by Fact() function that takes three arguments: test description, expected value, actual value. Such facts are grouped into test suites by packing them in a list. Test suites are executed with Facts.Summarize() function.

LibPQ provides its own implementation of Fact and Facts.Summarize functions. Those functions have the same API as the ones described in Microsoft's article but they produce different output to enable compatibility with LibPQ UnitTest framework.

To run fact based tests with LibPQ you need to import those functions into your test code. No other modifications are required.

// ...beginning of the test code (skipped)...

    // Import LibPQ functions that enable fact based tests
    Fact = LibPQ("UnitTest.Fact"),
    Facts.Summarize = LibPQ("UnitTest.Facts.Summarize"),

    // Sample fact based test
    Fact("Values should be equal (using a let statement)",
        "Hello World",
        let
            a = "Hello World"
        in
            a
    ),

// ...the rest of the test code (skipped)...

Test discovery for fact based tests

LibPQ UnitTest framework supports test discovery for fact based unit tests. To make your tests discoverable you need to:

• Store the test suite (list of facts) in a separate LibPQ module
• Add the following metadata to the test suite: LibPQ.TestSuite = "Facts"

Such test will be discovered and executed automatically by UnitTest.Discover. See sample test for more information.

Converting existing test code for use with LibPQ

The only thing you need to do to execute your existing fact based tests with LibPQ is to inject the LibPQ versions of Fact and Facts.Summarize functions into your test code. You can do that by adding the following import statements to your modules:

Fact = LibPQ("UnitTest.Fact"),
Facts.Summarize = LibPQ("UnitTest.Facts.Summarize"),

After that you can consider making your test suite discoverable by LibPQ (as described previously in this article).