Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ include(FetchContent)
FetchContent_Declare(
mu.tiny
GIT_REPOSITORY https://github.com/thetic/mu.tiny.git
GIT_TAG v0.8.1
FIND_PACKAGE_ARGS 0.8
GIT_TAG v0.9.0
FIND_PACKAGE_ARGS 0.9
)
FetchContent_MakeAvailable(mu.tiny)

Expand All @@ -44,7 +44,7 @@ If _mu::tiny_ is already installed and you prefer not to use
[`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html) directly:

```cmake
find_package(mu.tiny 0.8 REQUIRED)
find_package(mu.tiny 0.9 REQUIRED)
```

## Headers
Expand Down
2 changes: 1 addition & 1 deletion cfg/VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.8.1
0.9.0
6 changes: 3 additions & 3 deletions docs/getting-started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ is not installed, CMake fetches and builds it from source automatically:
FetchContent_Declare(
mu.tiny
GIT_REPOSITORY https://github.com/thetic/mu.tiny.git
GIT_TAG v0.8.1
FIND_PACKAGE_ARGS 0.8
GIT_TAG v0.9.0
FIND_PACKAGE_ARGS 0.9
)
FetchContent_MakeAvailable(mu.tiny)

Expand All @@ -47,7 +47,7 @@ If *mu::tiny* is already installed and you prefer not to use

.. code-block:: cmake

find_package(mu.tiny 0.8 REQUIRED)
find_package(mu.tiny 0.9 REQUIRED)

Headers
~~~~~~~
Expand Down
39 changes: 39 additions & 0 deletions docs/mocking.rst
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,45 @@ For custom types use
:cpp:func:`with_output_parameter_of_type() <mu::tiny::mock::ActualCall::with_output_parameter_of_type>`
with a registered copier.

Capturing Parameters
---------------------

Output parameters move data in a fixed, known direction: test → code under
test. Sometimes you need the opposite — inspecting a value the code under test
passes *into* a mocked call, such as a generated id, a timestamp, or a struct
it populated. :cpp:func:`with_parameter_of_type() <mu::tiny::mock::ExpectedCall::with_parameter_of_type>`
doesn't help here since it requires an exact match *during* the call; capturing
lets you grab the value and assert on it *after* the call.

On the expected side:

.. code-block:: cpp

Message captured;
mock().expect_one_call("send")
.with_captured_parameter_of_type("Message", "msg", &captured);

On the actual call side (in your mock implementation):

.. code-block:: cpp

mock().actual_call("send")
.with_captured_parameter_of_type("Message", "msg", msg);

.. code-block:: cpp

// Back in the test, after exercising the code under test:
CHECK_EQUAL(42, captured.id);

The framework copies the actual call's parameter into ``captured`` when the
call is matched — the mirror of `Output Parameters`_. For raw memory use
:cpp:func:`with_captured_parameter() <mu::tiny::mock::ExpectedCall::with_captured_parameter>` +
:cpp:func:`with_captured_parameter() <mu::tiny::mock::ActualCall::with_captured_parameter>`
(plain memcpy); for custom types use
:cpp:func:`with_captured_parameter_of_type() <mu::tiny::mock::ExpectedCall::with_captured_parameter_of_type>` +
:cpp:func:`with_captured_parameter_of_type() <mu::tiny::mock::ActualCall::with_captured_parameter_of_type>`
with a registered copier.

Return Values
-------------

Expand Down
4 changes: 2 additions & 2 deletions examples/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ if(PROJECT_IS_TOP_LEVEL)
FetchContent_Declare(
mu.tiny
GIT_REPOSITORY https://github.com/thetic/mu.tiny.git
GIT_TAG v0.8.1
FIND_PACKAGE_ARGS 0.8
GIT_TAG v0.9.0
FIND_PACKAGE_ARGS 0.9
)
FetchContent_MakeAvailable(mu.tiny)
endif()
Expand Down
50 changes: 50 additions & 0 deletions include/mu/tiny/mock.h
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,30 @@ extern "C"
void* value
);

/**
* @brief Report a captured parameter.
* @param name Parameter name.
* @param value Pointer to the data to copy into the test's buffer.
* @return this.
*/
struct MutinyMockActualCall* (*with_captured_parameter)(
const char* name,
const void* value
);

/**
* @brief Report a custom-type captured parameter.
* @param type Type name.
* @param name Parameter name.
* @param value Pointer to the object to copy into the test's buffer.
* @return this.
*/
struct MutinyMockActualCall* (*with_captured_parameter_of_type)(
const char* type,
const char* name,
const void* value
);

/** @return Non-zero if the expectation set a return value. */
int (*has_return_value)(void);

Expand Down Expand Up @@ -613,6 +637,32 @@ extern "C"
const char* name
);

/**
* @brief Capture a parameter (plain @c memcpy).
* @param name Name.
* @param value Buffer to copy the actual value into.
* @param size Bytes to copy.
* @return this.
*/
struct MutinyMockExpectedCall* (*with_captured_parameter)(
const char* name,
void* value,
size_t size
);

/**
* @brief Capture a parameter of a custom object type.
* @param type Type name.
* @param name Name.
* @param value Buffer to copy the actual object into.
* @return this.
*/
struct MutinyMockExpectedCall* (*with_captured_parameter_of_type)(
const char* type,
const char* name,
void* value
);

/**
* @brief Allow the actual call to pass extra unlisted parameters.
* @return this.
Expand Down
33 changes: 33 additions & 0 deletions include/mu/tiny/mock/ActualCall.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,39 @@ class MUTINY_EXPORT ActualCall
void* output
) = 0;

/**
* @brief Report a captured parameter by name.
*
* The framework copies @p value into the buffer configured on the
* matching expectation via @ref ExpectedCall::with_captured_parameter(),
* so the test can inspect it after the call. This is the mirror of
* with_output_parameter(): data flows from the actual call to the test
* instead of from the expectation to the actual call.
*
* @param name Parameter name.
* @param value Pointer to the data to copy into the test's buffer.
* @return *this for chaining.
*/
virtual ActualCall& with_captured_parameter(
StringView name,
const void* value
) = 0;

/**
* @brief Report a captured parameter with a custom object type.
*
* @param type_name Type name; must match the copier installed via
* @ref Support::install_copier().
* @param name Parameter name.
* @param value Pointer to the object to copy into the test's buffer.
* @return *this for chaining.
*/
virtual ActualCall& with_captured_parameter_of_type(
StringView type_name,
StringView name,
const void* value
) = 0;

/** @return true if the matching expectation set a return value. */
virtual bool has_return_value() = 0;
/** @return The configured return value as a generic NamedValue. */
Expand Down
37 changes: 37 additions & 0 deletions include/mu/tiny/mock/ExpectedCall.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,43 @@ class MUTINY_EXPORT ExpectedCall
*/
virtual ExpectedCall& with_unmodified_output_parameter(StringView name) = 0;

/**
* @brief Capture a parameter: the framework will copy the value the actual
* call reports for this parameter into @p value (plain memcpy).
*
* Use this instead of with_parameter_of_type() when the parameter's value
* can't be predicted ahead of time (a generated id, a timestamp, a struct
* populated by the code under test) and the test needs to inspect it after
* the call rather than compare it during the call.
*
* @param name Parameter name.
* @param value Pointer to the buffer to copy the actual value into.
* @param size Number of bytes to copy.
* @return *this for chaining.
*/
virtual ExpectedCall& with_captured_parameter(
StringView name,
void* value,
size_t size
) = 0;

/**
* @brief Capture a parameter of a custom object type.
*
* Uses the NamedValueCopier installed for @p type_name to copy the actual
* object into @p value.
*
* @param type_name Type name; must match the copier key.
* @param name Parameter name.
* @param value Pointer to the buffer to copy the actual object into.
* @return *this for chaining.
*/
virtual ExpectedCall& with_captured_parameter_of_type(
StringView type_name,
StringView name,
void* value
) = 0;

/**
* @brief Allow the actual call to pass parameters not listed in this
* expectation.
Expand Down
23 changes: 23 additions & 0 deletions src/mock/ActualCallTrace.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,29 @@ ActualCall& ActualCallTrace::with_output_parameter_of_type(
return *this;
}

ActualCall& ActualCallTrace::with_captured_parameter(
StringView name,
const void* value
)
{
add_parameter_name(name);
trace_buffer_ += string_from(value);
return *this;
}

ActualCall& ActualCallTrace::with_captured_parameter_of_type(
StringView type_name,
StringView name,
const void* value
)
{
trace_buffer_ += " ";
trace_buffer_ += type_name.c_str();
add_parameter_name(name);
trace_buffer_ += string_from(value);
return *this;
}

bool ActualCallTrace::has_return_value()
{
return false;
Expand Down
85 changes: 75 additions & 10 deletions src/mock/CheckedActualCall.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -64,18 +64,40 @@ void CheckedActualCall::copy_output_parameters(
p = p->next) {
NamedValue output_parameter = expected_call->get_output_parameter(p->name);
NamedValueCopier* copier = output_parameter.get_copier();
const bool to_actual_call =
(p->direction == MutinyCopyDirection::to_actual_call);
const bool raw_pointer_pair =
to_actual_call ? ((output_parameter.get_type() == "const void*") &&
(p->type == "void*"))
: ((output_parameter.get_type() == "void*") &&
(p->type == "const void*"));

if (copier != nullptr) {
copier->copy(p->ptr, output_parameter.get_const_object_pointer());
} else if (
(output_parameter.get_type() == "const void*") && (p->type == "void*")
) {
const void* data = output_parameter.get_value<const void*>();
size_t size = output_parameter.get_size();
memcpy(p->ptr, data, size);
if (to_actual_call) {
copier->copy(
const_cast<void*>(p->value),
output_parameter.get_const_object_pointer()
);
} else {
copier->copy(output_parameter.get_object_pointer(), p->value);
}
} else if (raw_pointer_pair) {
if (to_actual_call) {
memcpy(
const_cast<void*>(p->value),
output_parameter.get_value<const void*>(),
output_parameter.get_size()
);
} else {
memcpy(
output_parameter.get_value<void*>(),
p->value,
output_parameter.get_size()
);
}
} else if (!output_parameter.get_name().empty()) {
fail_with(NoWayToCopyCustomTypeFailure(
get_test(),
expected_call->get_output_parameter(p->name).get_type().c_str()
get_test(), output_parameter.get_type().c_str()
));
}
}
Expand Down Expand Up @@ -247,6 +269,35 @@ ActualCall& CheckedActualCall::with_output_parameter_of_type(
return *this;
}

ActualCall& CheckedActualCall::with_captured_parameter(
StringView name,
const void* value
)
{
add_captured_parameter(name, "const void*", value);

NamedValue captured_parameter(name);
captured_parameter.set_value(value);
check_output_parameter(static_cast<NamedValue&&>(captured_parameter));

return *this;
}

ActualCall& CheckedActualCall::with_captured_parameter_of_type(
StringView type,
StringView name,
const void* value
)
{
add_captured_parameter(name, type, value);

NamedValue captured_parameter(name);
captured_parameter.set_const_object_pointer(type, value);
check_output_parameter(static_cast<NamedValue&&>(captured_parameter));

return *this;
}

bool CheckedActualCall::is_fulfilled() const
{
return state_ == MutinyActualCallState::success;
Expand Down Expand Up @@ -353,8 +404,22 @@ void CheckedActualCall::add_output_parameter(
void* ptr
)
{
auto* new_node = new MockOutputParametersListNode(name, type, ptr);
add_output_parameter_node(new MockOutputParametersListNode(name, type, ptr));
}

void CheckedActualCall::add_captured_parameter(
StringView name,
StringView type,
const void* ptr
)
{
add_output_parameter_node(new MockOutputParametersListNode(name, type, ptr));
}

void CheckedActualCall::add_output_parameter_node(
MockOutputParametersListNode* new_node
)
{
if (output_parameter_expectations_ == nullptr) {
output_parameter_expectations_ = new_node;
} else {
Expand Down
Loading