[GD-1088] Add an option to include the stack trace for failed assertions

[powertomato]

Feature Type

New assertion/matcher

Problem/Use Case

Some testcases have a reoccurring set of assertions. In order to DRY it's sometimes useful to put them in a separate function.
The problem that then arises it's sometimes not enough to report the testcase and failed assertion alone to find out the location of the failure.

E.g. with this testcase:

func test_something() -> void:
    ...
    _my_custom_assert(obj1)
    ...
    _my_custom_assert(obj2)


func _my_custom_assert(obj) -> void:
    assert_int(obj.a).greater(42)
    assert_int(obj.b).equals(69)

The report would include
test_something failed, because e.g. obj.a is not greater than 42.

So without debugging it's not possible to distinguish if _my_custom_assert(obj1) or _my_custom_assert(obj2) caused the assertion

Proposed Solution

The simplest solution would be to just add an option to always include the entire call-stack.

Alternatively, one could add an API to let the test author how much of the call-stack would be included:
Add a function to include more of the calling context. .with_stack_context(depth)

• .with_stack_context(1) would include the last line the error occured, no change to current report (except also including the script-name):

my_tests.gd, line 52: Expecting to be greater than:  '42' but was '17'

• .with_stack_context(2) would include the last two calls:

my_tests.gd, line 10: test_something
my_tests.gd, line 52: Expecting to be greater than:  '42' but was '17'

• .with_stack_context() without an argument, would include the entire callstack:

my_tests.gd, line 10: test_something
abstract_test_utils, line 20: some_abstract_contraction
abstract_test_utils, line 450: we_re_past_regular_testcases
test_utils_impl, line 1337: i_guess_this_testcase_needs_a_testcase
my_tests.gd, line 52: Expecting to be greater than:  '42' but was '17'

Alternatives Considered

No response

Impact and Benefits

No response

Implementation Notes

No response

Examples and References

No response

Contribution

• I'm willing to contribute code for this feature
• I'm willing to help with testing/feedback
• I'm willing to help with documentation
• I would just like to request this feature

[MikeSchulze]

Thank you for this feature suggestion.
In my opinion, we don’t need an additional API function to control the stack trace.
It should be possible by default to extract the stack trace from the cause all the way back to the test function.

This would have the advantage that existing tests wouldn't need to be modified, and the stack trace would be generated out of the box as soon as the stack depth exceeds 1.