diff --git a/README b/README new file mode 100644 index 0000000..3c33660 --- /dev/null +++ b/README @@ -0,0 +1,10 @@ +Welcome to CMock. + +* Not sure what you're doing? +** The docs are in /docs +* Interested in our MIT-style license? +** That's in /docs too +* Are there examples? +** Try /examples +* Any other resources to check out? +** Sure. How about ThrowTheSwitch.org diff --git a/docs/CMock Summary.odt b/docs/CMock Summary.odt index fc04579..a37707e 100644 Binary files a/docs/CMock Summary.odt and b/docs/CMock Summary.odt differ diff --git a/docs/CMock Summary.pdf b/docs/CMock Summary.pdf index d9be965..fcd7c56 100644 Binary files a/docs/CMock Summary.pdf and b/docs/CMock Summary.pdf differ diff --git a/docs/CMock_Summary.md b/docs/CMock_Summary.md index c352693..43ce79d 100644 --- a/docs/CMock_Summary.md +++ b/docs/CMock_Summary.md @@ -1,82 +1,82 @@ -[All code is copyright © 2007-2010 Cmock Project +[All code is copyright © 2007-2014 Cmock Project by Mike Karlesky, Mark VanderVoord, and Greg Williams. -This Documentation Is Released Under a Creative Commons 3.0 -Attribution Share-Alike License] +This Documentation Is Released Under a Creative Commons 3.0 +Attribution Share-Alike License] What the What? ============== -CMock is a nice little tool which takes your header files and creates -a Mock interface for it so that you can more easily Unit test modules -that touch other modules. For each function prototype in your -header, like this one: +CMock is a nice little tool which takes your header files and creates +a Mock interface for it so that you can more easily Unit test modules +that touch other modules. For each function prototype in your +header, like this one: int DoesSomething(int a, int b); - -...you get an automatically generated DoesSomething function -that you can link to instead of your real DoesSomething function. -By using this Mocked version, you can then verify that it receives -the data you want, and make it return whatever data you desire, -make it throw errors when you want, and more... Create these for -everything your latest real module touches, and you're suddenly -in a position of power: You can control and verify every detail -of your latest creation. -To make that easier, CMock also gives you a bunch of functions -like the ones below, so you can tell that generated DoesSomething -function how to behave for each test: +...you get an automatically generated DoesSomething function +that you can link to instead of your real DoesSomething function. +By using this Mocked version, you can then verify that it receives +the data you want, and make it return whatever data you desire, +make it throw errors when you want, and more... Create these for +everything your latest real module touches, and you're suddenly +in a position of power: You can control and verify every detail +of your latest creation. + +To make that easier, CMock also gives you a bunch of functions +like the ones below, so you can tell that generated DoesSomething +function how to behave for each test: void DoesSomething_ExpectAndReturn(int a, int b, int toReturn); void DoesSomething_ExpectAndThrow(int a, int b, EXCEPTION_T error); void DoesSomething_StubWithCallback(CMOCK_DoesSomething_CALLBACK YourCallback); void DoesSomething_IgnoreAndReturn(int toReturn); - -You can pile a bunch of these back to back, and it remembers what -you wanted to pass when, like so: + +You can pile a bunch of these back to back, and it remembers what +you wanted to pass when, like so: test_CallsDoesSomething_ShouldDoJustThat(void) { DoesSomething_ExpectAndReturn(1,2,3); DoesSomething_ExpectAndReturn(4,5,6); DoesSomething_ExpectAndThrow(7,8, STATUS_ERROR_OOPS); - + CallsDoesSomething( ); } - -This test will call CallsDoesSomething, which is the function -we are testing. We are expecting that function to call DoesSomething -three times. The first time, we check to make sure it's called -as DoesSomething(1, 2) and we'll magically return a 3. The second -time we check for DoesSomething(4, 5) and we'll return a 6. The -third time we verify DoesSomething(7, 8) and we'll throw an error -instead of returning anything. If CallsDoesSomething gets -any of this wrong, it fails the test. It will fail if you didn't -call DoesSomething enough, or too much, or with the wrong arguments, -or in the wrong order. -CMock is based on Unity, which it uses for all internal testing. -It uses Ruby to do all the main work (versions 1.8.6 through 1.9.2). +This test will call CallsDoesSomething, which is the function +we are testing. We are expecting that function to call DoesSomething +three times. The first time, we check to make sure it's called +as DoesSomething(1, 2) and we'll magically return a 3. The second +time we check for DoesSomething(4, 5) and we'll return a 6. The +third time we verify DoesSomething(7, 8) and we'll throw an error +instead of returning anything. If CallsDoesSomething gets +any of this wrong, it fails the test. It will fail if you didn't +call DoesSomething enough, or too much, or with the wrong arguments, +or in the wrong order. + +CMock is based on Unity, which it uses for all internal testing. +It uses Ruby to do all the main work (versions 1.8.6 through 1.9.2). Generated Mock Module Summary ============================= -In addition to the mocks themselves, CMock will generate the -following functions for use in your tests. The expect functions -are always generated. The other functions are only generated -if those plugins are enabled: +In addition to the mocks themselves, CMock will generate the +following functions for use in your tests. The expect functions +are always generated. The other functions are only generated +if those plugins are enabled: Expect: ------- -Your basic staple Expects which will be used for most of your day -to day CMock work. +Your basic staple Expects which will be used for most of your day +to day CMock work. * `void func(void)` => `void func_Expect(void)` * `void func(params)` => `void func_Expect(expected_params)` @@ -87,9 +87,9 @@ to day CMock work. Array: ------ -An ExpectWithArray will check as many elements as you specify. -If you specify zero elements, it will check just the pointer if -`:smart` mode is configured or fail if `:compare_data` is set. +An ExpectWithArray will check as many elements as you specify. +If you specify zero elements, it will check just the pointer if +`:smart` mode is configured or fail if `:compare_data` is set. * `void func(void)` => (nothing. In fact, an additional function is only generated if the params list contains pointers) * `void func(ptr * param, other)` => `void func_ExpectWithArray(ptr* param, int param_depth, other)` @@ -100,11 +100,11 @@ If you specify zero elements, it will check just the pointer if Callback: --------- -As soon as you stub a callback in a test, it will call the callback -whenever the mock is encountered and return the retval returned -from the callback (if any) instead of performing the usual expect -checks. It can be configured to check the arguments first (like -expects) or just jump directly to the callback. +As soon as you stub a callback in a test, it will call the callback +whenever the mock is encountered and return the retval returned +from the callback (if any) instead of performing the usual expect +checks. It can be configured to check the arguments first (like +expects) or just jump directly to the callback. * `void func(void)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)` where `CMOCK_func_CALLBACK` looks like: `void func(int NumCalls)` @@ -119,10 +119,10 @@ where `CMOCK_func_CALLBACK` looks like: `retval func(params, int NumCalls)` Cexception: ----------- -If you are using Cexception for error handling, you can use this -to throw errors from inside mocks. Like Expects, it remembers -which call was supposed to throw the error, and it still checks -parameters. +If you are using Cexception for error handling, you can use this +to throw errors from inside mocks. Like Expects, it remembers +which call was supposed to throw the error, and it still checks +parameters. * `void func(void)` => `void func_ExpectAndThrow(value_to_throw)` * `void func(params)` => `void func_ExpectAndThrow(expected_params, value_to_throw)` @@ -133,10 +133,10 @@ parameters. Ignore: ------- -This plugin supports two modes. You can use it to force CMock to -ignore calls to specific functions or to just ignore the arguments -passed to those functions. Either way you can specify multiple -returns or a single value to always return, whichever you prefer. +This plugin supports two modes. You can use it to force CMock to +ignore calls to specific functions or to just ignore the arguments +passed to those functions. Either way you can specify multiple +returns or a single value to always return, whichever you prefer. * `void func(void)` => `void func_Ignore(void)` * `void func(params)` => `void func_Ignore(void)` @@ -144,62 +144,86 @@ returns or a single value to always return, whichever you prefer. * `retval func(params)` => `void func_IgnoreAndReturn(retval_to_return)` +Ignore Args: +------------ + +This plugin adds the ability to specify specifc arguments to ignore +for a function, instead of ignoring all the arguments or the entire +function call, as the Ignore plugin supports. This will create a function +for each argument and each function. + +* `void func(params)` => `void func_IgnoreArg_paramName(void)` + + +ReturnThruPtr: +-------------- + +This plugin adds a number of options for returning data through arguments +that are pointers. This is fled separately from the Expect/Ignore call, so +you will want to issue one of those calls each time as well. This will only +create an extra call for arguments that are pointers. It will create one per +pointer argument. + +* `void func(param1)` => `void func_ReturnThruPtr_paramName(val_to_return)` +* => `void func_ReturnArrayThruPtr_paramName(cal_to_return, len)` +* => `void func_ReturnMemThruPtr_paramName(val_to_return, size)` + Running CMock ============= -CMock is a Ruby script and class. You can therefore use it directly -from the command line, or include it in your own scripts or rakefiles. +CMock is a Ruby script and class. You can therefore use it directly +from the command line, or include it in your own scripts or rakefiles. Mocking from the Command Line ----------------------------- -After unpacking CMock, you will find CMock.rb in the 'lib' directory. -This is the file that you want to run. It takes a list of header files -to be mocked, as well as an optional yaml file for a more detailed -configuration (see config options below). +After unpacking CMock, you will find CMock.rb in the 'lib' directory. +This is the file that you want to run. It takes a list of header files +to be mocked, as well as an optional yaml file for a more detailed +configuration (see config options below). -For example, this will create three mocks using the configuration -specified in MyConfig.yml: +For example, this will create three mocks using the configuration +specified in MyConfig.yml: ruby cmock.rb -oMyConfig.yml super.h duper.h awesome.h -And this will create two mocks using the default configuration: +And this will create two mocks using the default configuration: ruby cmock.rb ../mocking/stuff/is/fun.h ../try/it/yourself.h Mocking From Scripts or Rake ---------------------------- -CMock can be used directly from your own scripts or from a rakefile. -Start by including cmock.rb, then create an instance of CMock. -When you create your instance, you may initialize it in one of -three ways. +CMock can be used directly from your own scripts or from a rakefile. +Start by including cmock.rb, then create an instance of CMock. +When you create your instance, you may initialize it in one of +three ways. -You may specify nothing, allowing it to run with default settings: +You may specify nothing, allowing it to run with default settings: cmock = CMock.new -You may specify a YAML file containing the configuration options -you desire: +You may specify a YAML file containing the configuration options +you desire: cmock = CMock.new('../MyConfig.yml') -You may specify the options explicitly: +You may specify the options explicitly: cmock = Cmock.new(:plugins => [:cexception, :ignore], :mock_path => 'my/mocks/') -Config Options: +Config Options: -The following configuration options can be specified in the -yaml file or directly when instantiating. +The following configuration options can be specified in the +yaml file or directly when instantiating. -Passed as Ruby, they look like this: +Passed as Ruby, they look like this: { :attributes => [“__funky”, “__intrinsic”], :when_ptr => :compare } -Defined in the yaml file, they look more like this: +Defined in the yaml file, they look more like this: - :cmock: + :cmock: :attributes: - __funky - __intrinsic @@ -267,8 +291,8 @@ Defined in the yaml file, they look more like this: * `:plugins`: An array of which plugins to enable. 'expect' is always active. Also - available currently are `:ignore,` `:array,` `:cexception,` and - `:callback: + available currently are `:ignore,` `:ignore_args,` `:array,` + `:cexception,` `:callback,` and `:return_thru_ptr` * `:treat_as`: The `:treat_as` list is a shortcut for when you have created typedefs @@ -320,37 +344,37 @@ Defined in the yaml file, they look more like this: Compiled Options: ----------------- -A number of #defines also exist for customizing the cmock experience. +A number of #defines also exist for customizing the cmock experience. -CMOCK_MEM_STATIC or CMOCK_MEM_DYNAMIC +CMOCK_MEM_STATIC or CMOCK_MEM_DYNAMIC -Define one of these to determine if you want to dynamically add -memory during tests as required from the heap. If static, you -can control the total footprint of Cmock. If dynamic, you will -need to make sure you make some heap space available for Cmock. +Define one of these to determine if you want to dynamically add +memory during tests as required from the heap. If static, you +can control the total footprint of Cmock. If dynamic, you will +need to make sure you make some heap space available for Cmock. -CMOCK_MEM_SIZE +CMOCK_MEM_SIZE -In static mode this is the total amount of memory you are allocating -to Cmock. In Dynamic mode this is the size of each chunk allocated -at once (larger numbers grab more memory but require less mallocs). +In static mode this is the total amount of memory you are allocating +to Cmock. In Dynamic mode this is the size of each chunk allocated +at once (larger numbers grab more memory but require less mallocs). -CMOCK_MEM_ALIGN +CMOCK_MEM_ALIGN -The way to align your data to. Not everything is as flexible as -a PC, as most embedded designers know. This defaults to 2, meaning -align to the closest 2^2 -> 4 bytes (32 bits). You can turn off alignment -by setting 0, force alignment to the closest uint16 with 1 or even -to the closest uint64 with 3. +The way to align your data to. Not everything is as flexible as +a PC, as most embedded designers know. This defaults to 2, meaning +align to the closest 2^2 -> 4 bytes (32 bits). You can turn off alignment +by setting 0, force alignment to the closest uint16 with 1 or even +to the closest uint64 with 3. -CMOCK_MEM_PTR_AS_INT +CMOCK_MEM_PTR_AS_INT -This is used internally to hold pointers... it needs to be big -enough. On most processors a pointer is the same as an unsigned -long... but maybe that's not true for yours? +This is used internally to hold pointers... it needs to be big +enough. On most processors a pointer is the same as an unsigned +long... but maybe that's not true for yours? -CMOCK_MEM_INDEX_TYPE +CMOCK_MEM_INDEX_TYPE -This needs to be something big enough to point anywhere in Cmock's -memory space... usually it's an unsigned int. +This needs to be something big enough to point anywhere in Cmock's +memory space... usually it's an unsigned int. diff --git a/docs/license.txt b/docs/license.txt index c58cb08..1e546fe 100644 --- a/docs/license.txt +++ b/docs/license.txt @@ -1,4 +1,4 @@ - Copyright (c) 2007 Mike Karlesky, Mark VanderVoord, Greg Williams + Copyright (c) 2007-14 Mike Karlesky, Mark VanderVoord, Greg Williams Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation