Assertions

Definition

Test assertions are conditions used in automated tests to check whether an expected result or behavior in a software application has been achieved. They are used to validate that the output of a test matches the expected result, and to identify any discrepancies or bugs in the application. Test assertions can be used for a variety of purposes, such as verifying the correctness of calculations, checking the behavior of user interfaces, or ensuring that data is properly stored and retrieved. Test assertions typically involve comparing actual results with expected results using comparison operators, such as equal to, greater than, less than, etc. If the assertion fails, it means that the test has identified a problem or bug in the application, and further investigation is needed to determine the cause and fix the issue.

How GdUnit Asserts compares Objects

In GdUnit, asserts generally compare objects based on parameter equality. This means that two objects of different instances are considered equal if they are of the same type and have the same parameter values.

For object reference comparison, GdUnit provides separate validation functions such as is_same and is_not_same, as well as assert-specific functions that handle reference comparison, such as contains_same or not_contains_same. These functions allow you to specifically check if two objects refer to the same instance or not.

Here is an example of using assert to compare objects:

extends GdUnitTestSuite

class TestClass:
 var _value :int
 
 func _init(value :int):
  _value = value


func test_typ_and_parameter_comparison():
 var obj1 = TestClass.new(1)
 var obj2 = TestClass.new(1)
 var obj3 = TestClass.new(2)
  
 # Using is_equal to check if obj1 and obj2 are equal but not same
 assert_object(obj1).is_equal(obj2)
  
 # Using is_not_equal to check if obj1 and obj3 do not equal, the value are different
 assert_object(obj1).is_not_equal(obj3)


func test_object_reference_comparison():
 var obj1 = TestClass.new(1)
 var obj2 = obj1
 var obj3 = TestClass.new(2)
  
 # Using is_same to check if obj1 and obj2 refer to the same instance
 assert_object(obj1).is_same(obj2)
  
 # Using is_not_same to check if obj1 and obj3 do not refer to the same instance
 assert_object(obj1).is_not_same(obj3)

How to use GdUnit assets to verify things

GdUnit4 provides a set of assertions that give you helpful error messages and improve the readability of your test code. Assertions are organized by type and support fluent syntax writing.
The pattern for using asserts is defined as assert_<type>(<current>).<comparison function>([expected]). If you don’t know the type of the current value, use the generic assert_that(<current>) instead.

Here is an example:

  • Asserts are restricted by GdScript behavior and therefore do not fully support generics. Therefore, you should prefer to use assert by type.

    For example, use assert_str for string.

    class_name GdUnitExampleTest
extends GdUnitTestSuite

func test_hello_world() -> void:
    # Using type save assert
    assert_str("Hello world").is_equal("Hello world")
    # Using the generic assert
    assert_that("Hello world").is_equal("Hello world")

  • The C# assert is smart and switches to the equivalent assert implementation by auto-typing and should also be used preferentially. Alternatively, you can use the typed asserts if you want to. To use the assert, you have to import it via static GdUnit4.Assertions.

    using GdUnit4;
using static GdUnit4.Assertions;

namespace ExampleProject.Tests
{
    [TestSuite]
    public class ExampleTest
    {
        [TestCase]
        public void HelloWorld()
        {
            AssertThat("Hello world").IsEqual("Hello world");
            // Using explicit the typed version
            AssertString("Hello world").IsEqual("Hello world");
        }
    }
}
Advice
You should use the fluent syntax to keep your tests clearer. 
  • class_name GdUnitExampleTest
extends GdUnitTestSuite

# A bad example for the multiple use of `assert_str`.
func test_hello_world() -> void:
    var current := "Hello World"
    assert_str(current).is_equal("Hello World")
    assert_str(current).contains("World")
    assert_str(current).not_contains("Green")

# A good example of using fluent syntax to write more readable tests
func test_hello_world_fluent() -> void:
    assert_str("Hello World")\
     .is_equal("Hello World")\
     .contains("World")\
     .not_contains("Green")

  • using GdUnit4;
using static GdUnit4.Assertions;

namespace ExampleProject.Tests
{
    [TestSuite]
    public class ExampleTest
    {
        // A bad example for the multiple use of `AssertThat`.
        [TestCase]
        public void HelloWorld()
        {
            string current = "Hello World";
            AssertThat(current).IsEqual("Hello World");
            AssertThat(current).Contains("World");
            AssertThat(current).NotContains("Green");
        }

        // A good example of using fluent syntax to write more readable tests
        [TestCase]
        public void HelloWorldFluent()
        {
            AssertThat("Hello World")
                .IsEqual("Hello World")
                .Contains("World")
                .NotContains("Green");
        }
    }
}

How to Override the Failure Message

By default, GdUnit generates a failure report based on the used assert, according to the expected vs. current value scheme. However, in some cases, the default failure message may not be specific enough or helpful to the reader. In those cases, you can override the default failure message using the override_failure_message function.

To use this function, simply call it on the assertion and pass in a custom failure message as a string. For example:

    func test_custom_failure_message() -> void:
        assert_str("Hello World")\
            # Override the default failure message with a custom one
            .override_failure_message("This is a customized failure message!")\
            # Let the test fail
            .is_empty()

The Generic Assert

The generic assert, assert_that (in GdScript) and AssertThat (in C#), can be used for all types and gives you access to the basic test functions of GdUnit Assert.
However, it is recommended to use the type-safe asserts whenever possible to ensure type safety in your tests.

Assert Type
assert_that auto typing (not type-safe)
AssertThat auto typing (type-safe)

The Basic Build-In Type Asserts

For more details about Build-In types click here Godot Build-In Types

Container Built-In Type Asserts

For more details about Build-In types click here Container built-in types

Engine Build-In Type Asserts

Engine Tool Asserts

Copyright © 2021-2024 Mike Schulze. Distributed by an MIT license.