ArgumentMatchers - MikeSchulze/gdUnit3 Wiki

🚨 github-wiki-see.page does not render Org-Mode. Source for crawling below. Please visit the Original URL! 🚨


* Argument Matchers

** Definition

An argument matcher is designed to help verify the behavior of a function call by a specified argument type.

That means we can test the call of a function without having to specify the exact argument value(s).

#+BEGIN_QUOTE
``` python
	# instead of testing by an exact argument value
	verify(mock, 2).set_message("This is a test")
	# If you only interested the fuction is called 2 times by any string value you can simplify by
	verify(mock, 2).set_message(any_string())

#+END_QUOTE

** Argument Matcher

#+BEGIN_QUOTE

verify(<mock>, <times>).function(<arg_matcher>)
verify(<spy>, <times>).function(<arg_matcher>)

Example of using the argument matcher on a mock

	mocked_node.set_process(false) # 1 times
	mocked_node.set_process(true) # 1 times
	mocked_node.set_process(true) # 2 times
	# use argument matcher 'any_bool' to count the function calls with an boolean value
	verify(mocked_node, 3).set_process(any_bool())

#+END_QUOTE

GdUnit offers a number of argument matchers with which you can verify the behavior of function calls with an argument according to a certain type. |Argument Matcher|Description| |any() | Argument matcher to match any argument| |any_bool() | Argument matcher to match any boolean value| |any_int() | Argument matcher to match any integer value| |any_float() | Argument matcher to match any float value| |any_string() | Argument matcher to match any string value| |any_class(class) | Argument matcher to match any instance of given class| (since GdUnit3 v0.9.3) |any_color() | Argument matcher to match any Color value| |any_vector2() | Argument matcher to match any Vector2 value| |any_vector3() | Argument matcher to match any Vector3 value| |any_rect2() | Argument matcher to match any Rect2 value| |any_plane() | Argument matcher to match any Plane value| |any_quat() | Argument matcher to match any Quat value| |any_aabb() | Argument matcher to match any AABB value| |any_basis() | Argument matcher to match any Basis value| |any_transform() | Argument matcher to match any Transform value| |any_transform_2d() | Argument matcher to match any Transform2D value| |any_node_path() | Argument matcher to match any NodePath value| |any_rid() | Argument matcher to match any RID value| |any_object() | Argument matcher to match any Object value| |any_dictionary() | Argument matcher to match any Dictionary value| |any_array() | Argument matcher to match any Array value| |any_pool_byte_array() | Argument matcher to match any PoolByteArray value| |any_pool_int_array() | Argument matcher to match any PoolIntArray value| |any_pool_float_array() | Argument matcher to match any PoolRealArray value| |any_pool_string_array() | Argument matcher to match any PoolStringArray value| |any_pool_vector2_array() | Argument matcher to match any PoolVector2Array value| |any_pool_vector3_array() | Argument matcher to match any PoolVector3Array value| |any_pool_color_array() | Argument matcher to match any PoolColorArray value|

** Custom Argument Matcher You can also just write your own argument matcher if it necessary. You can do this by extend from class GdUnitArgumentMatcher and implement the is_match function.

#+BEGIN_QUOTE

# base class of all argument matchers
class_name GdUnitArgumentMatcher
extends Reference


func is_match(value) -> bool:
	return true

#+END_QUOTE

Here an simple example of an custom argument matcher. #+BEGIN_QUOTE

class_name MyClass
extends Reference

var _value:int

func set_value(value :int):
	_value = value
class CustomArgumentMatcher extends GdUnitArgumentMatcher:
	var _peek :int
	
	func _init(peek :int):
		_peek = peek

	func is_match(value) -> bool:
		return value > _peek

func test_custom_matcher():
	var mocked_test_class : MyClass = mock(MyClass)
	
	mocked_test_class.set_value(1000)
	mocked_test_class.set_value(1001)
	mocked_test_class.set_value(1002)
	mocked_test_class.set_value(2002)
	
	# counts 1001, 1002, 2002 = 3 times
	verify(mocked_test_class, 3).set_value(CustomArgumentMatcher.new(1000))
	# counts 2002 = 1 times
	verify(mocked_test_class, 1).set_value(CustomArgumentMatcher.new(2000))

#+END_QUOTE