diff --git a/doc/cgreen-guide-en.asciidoc b/doc/cgreen-guide-en.asciidoc index e47a7c4e..d7b4b787 100644 --- a/doc/cgreen-guide-en.asciidoc +++ b/doc/cgreen-guide-en.asciidoc @@ -1640,13 +1640,13 @@ Ensure(Readline, can_read_some_characters) { char canned_c = 'c'; expect(mocked_read, - will_set_contents_of_parameter(buf, &canned_a, sizeof(char)), + will_set_contents_of_output_parameter(buf, &canned_a, sizeof(char)), will_return(1)); expect(mocked_read, - will_set_contents_of_parameter(buf, &canned_b, sizeof(char)), + will_set_contents_of_output_parameter(buf, &canned_b, sizeof(char)), will_return(1)); expect(mocked_read, - will_set_contents_of_parameter(buf, &canned_c, sizeof(char)), + will_set_contents_of_output_parameter(buf, &canned_c, sizeof(char)), will_return(1)); ... @@ -1660,7 +1660,7 @@ It is very tempting to break out the common expect: ----------------------------- static void expect_char(char ch) { expect(mocked_read, - will_set_contents_of_parameter(buf, &ch, sizeof(char)), + will_set_contents_of_output_parameter(buf, &ch, sizeof(char)), will_return(1)); } @@ -1694,7 +1694,7 @@ At first glance the fix might look easy: static void expect_char(char ch) { char saved_ch = ch; expect(mocked_read, - will_set_contents_of_parameter(buf, &saved_ch, sizeof(char)), + will_set_contents_of_output_parameter(buf, &saved_ch, sizeof(char)), will_return(1)); } @@ -1711,7 +1711,7 @@ Ok, so let's make it static: static void expect_char(char ch) { static char saved_ch = ch; expect(mocked_read, - will_set_contents_of_parameter(buf, &saved_ch, sizeof(char)), + will_set_contents_of_output_parameter(buf, &saved_ch, sizeof(char)), will_return(1)); } @@ -1747,7 +1747,7 @@ The solution is now quite obvious: ----------------------------- static void expect_char(char *ch_p) { expect(mocked_read, - will_set_contents_of_parameter(buf, ch_p, sizeof(char)), + will_set_contents_of_output_parameter(buf, ch_p, sizeof(char)), will_return(1)); } @@ -1780,7 +1780,7 @@ CAUTION: Variables that are to be sent to a mocked function MUST be live at the In C all function parameters are by value so if a function needs to return a value through a parameter that has to be done using a pointer. Typically this is a pointer to the area or variable the function should fill. -*Cgreen* provides `will_set_contents_of_parameter()` to handle this use case. +*Cgreen* provides `will_set_contents_of_output_parameter()` to handle this use case. For example [source, c] @@ -1795,7 +1795,7 @@ When the mock for `convert_to_uppercase()` is called it will write the string "U ==== Setting fields Sometimes you need to set a field in a struct sent by reference to a mocked function. -You cannot use the `will_set_contents_of_parameter()` directly since you can't, or even don't want to, know the complete information in the structure. +You cannot use the `will_set_contents_of_output_parameter()` directly since you can't, or even don't want to, know the complete information in the structure. But with a little bit of boilerplate in your mock function you can still write to a single field. In the mock function you need to create a local variable that points to the field you want to update. @@ -1810,9 +1810,9 @@ include::tutorial_src/set_field.c[lines=3..18] ----------------------- The local variable `field` in the mock function is set to point to the field that we need to update. -It is then exposed by including it in the `mock()` call, and `will_set_contents_of_parameter()` will use it to update whatever it points to with the data provided in the `expect()`. +It is then exposed by including it in the `mock()` call, and `will_set_contents_of_output_parameter()` will use it to update whatever it points to with the data provided in the `expect()`. -NOTE: Both the local variable and the data argument in the call to `will_set_contents_of_parameter()` must be pointers. +NOTE: Both the local variable and the data argument in the call to `will_set_contents_of_output_parameter()` must be pointers. You cannot use literals as data, except when it is a string literal which as per C convention is converted to a pointer. ==== Side Effects @@ -1892,7 +1892,7 @@ In your mocked function you can then simply return that value, or manipulate it |`will_return(value)` | return `value`, for integer types |`will_return_double(value)` | return `value` as a "boxed double", for double floats (required because of C's type coercion rules which would otherwise convert a double into an int) |`will_return_by_value(struct, size)` | return a pointer to an allocated copy of the `struct` that can be copied and returned by value from the mocked function -|`will_set_contents_of_parameter(parameter_name, pointer_to_value, size)`| write `size` bytes from the pointed out value (`pointer_to_value`) into where the referenced out parameter (`parameter_name`) is pointing +|`will_set_contents_of_output_parameter(parameter_name, pointer_to_value, size)`| write `size` bytes from the pointed out value (`pointer_to_value`) into where the referenced out parameter (`parameter_name`) is pointing |`will_capture_parameter(parameter_name, local_variable)` |capture the value of the parameter and store it in the named local variable |`with_side_effect(function, pointer_to_data)` | call the side effect `function` and pass `pointer_to_data` to it |=========================================================================================== @@ -1901,7 +1901,9 @@ NOTE: *`will_return_double()`*: The "boxed double" returned by `mock()` have to NOTE: *`will_return_by_value`*: The memory allocated for the copy of the struct returned by `mock()` needs to be deallocated by the caller or it will be lost. You can do this with the code in the `Box` example below. -NOTE: *`will_set_contents_of_parameter`*: The data to set must be correct at the time of the call to the mock function, and not be overwritten or released between the call to the `expect()` and the mock function. See <> for details. +NOTE: *`will_set_contents_of_output_parameter`*: The data to set must be correct at the time of the call to the mock function, and not be overwritten or released between the call to the `expect()` and the mock function. See <> for details. + +NOTE: *`will_set_contents_of_output_parameter`*: The previous name of this macro was `will_set_contents_of_parameter` and it is still available. The new name is prefered due to readability. NOTE: *`will_capture_parameter`*: The local variable to capture the value in must be live at the time of the call to the mock function, so using a local variable in a function called by your test will not work. See <> for details. @@ -1918,13 +1920,13 @@ You can combine the expectations for a `mock()` in various ways: when(file, is_equal_to_contents_of(&FD, sizeof(FD))), when(input, is_equal_to_string("Hello world!"), with_side_effect(&update_counter, &counter), - will_set_contents_of_parameter(status, FD_CLOSED, sizeof(bool)))); + will_set_contents_of_output_parameter(status, FD_CLOSED, sizeof(bool)))); ----------------------- If multiple `when()` are specified they all need to be fullfilled. You can of course only have one for each of the parameters of your mock function. -You can also have multiple `will_set_contents_of_parameter()` in an expectation, one for each reference parameter, but naturally only one `will_return()`. +You can also have multiple `will_set_contents_of_output_parameter()` in an expectation, one for each reference parameter, but naturally only one `will_return()`. To ensure that a specific call happens `n` times the macro `times(number_times_called)` can be passed as a constraint to a specific call: @@ -1978,7 +1980,7 @@ The expectation code should look like the following === Handling out-parameters -TBD. Hint: this involves using `will_set_contents_of_parameter()`. +TBD. Hint: this involves using `will_set_contents_of_output_parameter()`. === Returning `struct` diff --git a/doc/tutorial_src/set_contents.c b/doc/tutorial_src/set_contents.c index 3877c253..0a0490a8 100644 --- a/doc/tutorial_src/set_contents.c +++ b/doc/tutorial_src/set_contents.c @@ -8,7 +8,7 @@ void convert_to_uppercase(char *converted_string, const char *original_string) { Ensure(setting_content_of_out_parameter) { expect(convert_to_uppercase, when(original_string, is_equal_to_string("upper case")), - will_set_contents_of_parameter(converted_string, + will_set_contents_of_output_parameter(converted_string, "UPPER CASE", 11)); } diff --git a/doc/tutorial_src/set_field.c b/doc/tutorial_src/set_field.c index 4df3e46b..06d248c0 100644 --- a/doc/tutorial_src/set_field.c +++ b/doc/tutorial_src/set_field.c @@ -14,5 +14,5 @@ void update_field(struct structure *struct_to_update) { Ensure(setting_field_of_parameter) { int fourty_two = 42; expect(update_field, - will_set_contents_of_parameter(field, &fourty_two, sizeof(int))); + will_set_contents_of_output_parameter(field, &fourty_two, sizeof(int))); } diff --git a/include/cgreen/constraint_syntax_helpers.h b/include/cgreen/constraint_syntax_helpers.h index 0e072cf7..baab46ba 100644 --- a/include/cgreen/constraint_syntax_helpers.h +++ b/include/cgreen/constraint_syntax_helpers.h @@ -51,6 +51,7 @@ #define will_return_by_value(value, size) create_return_by_value_constraint((intptr_t)&value, size) #define will_return_double(value) create_return_double_value_constraint(value) #define will_set_contents_of_parameter(parameter_name, pointer_to_value, size) create_set_parameter_value_constraint(#parameter_name, (intptr_t)pointer_to_value, (size_t)size) +#define will_set_contents_of_output_parameter(parameter_name, pointer_to_value, size) create_set_parameter_value_constraint(#parameter_name, (intptr_t)pointer_to_value, (size_t)size) #define will_capture_parameter(parameter_name, local_variable) create_capture_parameter_constraint(#parameter_name, &local_variable, sizeof(local_variable)) #endif diff --git a/tests/api/core_api.c b/tests/api/core_api.c index d2743afd..3584946e 100644 --- a/tests/api/core_api.c +++ b/tests/api/core_api.c @@ -46,7 +46,7 @@ static int int_stub(int parameter) { // Mocks Ensure(mocks_compiles) { always_expect(int_stub, will_return(1)); - always_expect(int_stub, will_set_contents_of_parameter(parameter, 1, sizeof(int))); + always_expect(int_stub, will_set_contents_of_output_parameter(parameter, 1, sizeof(int))); never_expect(int_stub); expect(int_stub, when(parameter, is_equal_to(1))); int_stub(1); diff --git a/tests/mocks_tests.c b/tests/mocks_tests.c index b5977b5e..a52db383 100644 --- a/tests/mocks_tests.c +++ b/tests/mocks_tests.c @@ -355,7 +355,7 @@ Ensure(Mocks, can_stub_an_out_parameter) { LargerThanIntptr local = { 4.13, 7.89, "alice" }; expect(out_param_mock, - will_set_contents_of_parameter(result, &actual, sizeof(LargerThanIntptr)) + will_set_contents_of_output_parameter(result, &actual, sizeof(LargerThanIntptr)) ); out_param_mock(&local); @@ -373,7 +373,7 @@ Ensure(Mocks, can_stub_a_char_out_parameter) { char stubbed_char = 'a'; char returned_char; expect(mocked_read, - will_set_contents_of_parameter(ch, &stubbed_char, 1)); + will_set_contents_of_output_parameter(ch, &stubbed_char, 1)); mocked_read(&returned_char); assert_that(returned_char, is_equal_to(stubbed_char)); } diff --git a/tools/discoverer_unit_tests.c b/tools/discoverer_unit_tests.c index 5f8d9456..1e677038 100644 --- a/tools/discoverer_unit_tests.c +++ b/tools/discoverer_unit_tests.c @@ -47,7 +47,7 @@ static void expect_read_line_from(int file_id, const char *line) { will_return(EOF)); else expect(read_line, when(file, is_equal_to(file_id)), - will_set_contents_of_parameter(buffer, line, strlen(line)+1), + will_set_contents_of_output_parameter(buffer, line, strlen(line)+1), will_return(strlen(line)+1)); }