Function tests

example/default/tests/template/behavior.cpp:56–124

<!-- description --> @brief Used to execute the actual checks. We put the checks in this function so that we can validate the tests both at compile-time and at run-time. If a bsl::ut_check fails, the tests will either fail fast at run-time, or will produce a compile-time error. <!-- inputs/outputs --> @return Always returns bsl::exit_success.

    ///   @return Always returns bsl::exit_success.
    ///
    [[nodiscard]] constexpr auto
    tests() noexcept -> bsl::exit_code
    {
        /// NOTE:
        /// - The tests() function is executed both at compile-time and at
        ///   runtime. This is done using the following at the bottom of this
        ///   file.
        ///
        ///   static_assert(example::tests() == bsl::ut_success());
        ///   return example::tests();
        ///
        /// - Anything executed in a static_assert is executed at compile-time
        ///   while the other call is your typical runtime call.
        ///

        /// NOTE:
        /// - BSL unit tests use behavioral driven unit testing.
        ///   https://en.wikipedia.org/wiki/Behavior-driven_development
        ///
        /// - All of these calls are syntactic sugar, meaning they do
        ///   absolutely nothing, except to ensure you are setting up your
        ///   tests using behavioral driven methods. The actual work is
        ///   performed by the following:
        ///   - bsl::ut_check() - used inside bsl::ut_then, and is used to
        ///     verify the results of your unit test
        ///   - bsl::ut_required_step() - used inside of bsl::ut_when, and
        ///     is used to verify that your unit test's set up is correct.
        ///

        bsl::ut_scenario{"this is what I am testing"} = [&]() noexcept {
            bsl::ut_given{"given the following"} = [&]() noexcept {
                /// add variables here
                bsl::ut_when{"when we do the following"} = [&]() noexcept {
                    /// add function calls here
                    bsl::ut_then{"we expect the following"} = [&]() noexcept {
                        /// add results checking here
                    };
                };
            };
        };

        /// NOTE:
        /// - There are a couple of different ways to do this. Once way
        ///   is to group tests under the same scenario as follows:
        ///

        bsl::ut_scenario{"verify +="} = [&]() noexcept {
            bsl::ut_given{} = [&]() noexcept {
                constexpr auto data1{42_umx};
                bsl::safe_umx mut_data2{};
                bsl::ut_when{} = [&]() noexcept {
                    mut_data2 += data1;
                    bsl::ut_then{"adds correctly"} = [&]() noexcept {
                        bsl::ut_check(mut_data2.checked() == data1);
                    };
                };
            };