Skip to content

Commit 1b71383

Browse files
fdefelicifdefelici
authored
Merge pull request #31 from fdefelici/issue-25-CmdLine_api_Selective_Tests_Run
Issue 25 cmd line api selective tests run
2 parents 49f002f + af87218 commit 1b71383

25 files changed

Lines changed: 1382 additions & 170 deletions

‎CMakeLists.txt‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,3 @@ add_subdirectory(examples/clovepp)
88
if (NOT DEFINED CI_TRIGGERED)
99
add_subdirectory(perfs)
1010
endif()
11-
12-
enable_testing()
13-
add_test(NAME CLoveUnitTest COMMAND CLoveUnitTest)

‎README.md‎

Lines changed: 75 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,34 @@
1-
# CLove-Unit · [![version](https://img.shields.io/badge/version-v2.2.3-blue)](./clove-unit.h) [![workflow](https://img.shields.io/github/workflow/status/fdefelici/clove-unit/CI%20Action)](https://github.com/fdefelici/clove-unit/actions/workflows/ci_action.yml)
2-
CLove Unit is a unit testing single-header library for C (mainly, but could also work with C++), with test autodiscovery feature.
1+
# CLove-Unit · [![version](https://img.shields.io/badge/version-v2.2.4-blue)](./clove-unit.h) [![workflow](https://img.shields.io/github/workflow/status/fdefelici/clove-unit/CI%20Action)](https://github.com/fdefelici/clove-unit/actions/workflows/ci_action.yml)
2+
`CLove-Unit` is a unit testing single-header library for C (mainly, but could also work with C++), with test autodiscovery feature.
33

4-
The aim of this library is to reduce at the minimum the boilder-plate and just focus on unit test development (such as avoiding to register manually the tests to an execution list).
4+
The aim of this library is to reduce at the minimum the boilder-plate for C developers and just focus on unit test development (such as avoiding to register manually the tests to an execution list).
55

6-
CLove Unit is able to discover and run your tests, gathering information about positives and failures (file, line, reason), with a colored syntax (if supported by your shell).
6+
`CLove-Unit` is able to discover and run your tests, gathering information about positives and failures (file, line, reason), with a colored syntax (if ANSI is supported by your shell).
77

88
![Clove test run result](./examples/result.png)
99

10-
> Futhermore an Extension for `Visual Studio Code` IDE is available in the [market place](https://marketplace.visualstudio.com/items?itemName=fdefelici.vscode-clove-unit). Have a look and enjoy ;-)
10+
# Features
11+
Here a list of features provided by `CLove-Unit`:
12+
* Single Header
13+
* Tests Autodiscovery (reducing at minimum developer boiler-plate on writing tests)
14+
* Console Report in ANSI format (if supported by the shell)
15+
* Tests / Run duration
16+
* Tests / Run failure pointing to the file/line where the assertions are unsatisfied
17+
* Selective test execution (opportunity to include/exclude tests from the execution)
18+
19+
# IDE Exstension
20+
For the one, who prefer UI oriented test executor, `CLove-Unit` is supported on the following IDEs:
21+
* `Visual Studio Code`: Extension is available from the [VSCode Market Place](https://marketplace.visualstudio.com/items?itemName=fdefelici.vscode-clove-unit).
22+
23+
Have a look and enjoy ;-)
1124

1225
# How it works
13-
CLove Unit is implemented around the following concepts:
26+
`CLove-Unit` is implemented around the following concepts:
1427
- **Test**: a test is basically a fuction where you can stimulate your code and validate it using assertion
1528
- **Suite**: a suite is a set of Tests to be run. A Suite allow to execute setup/teardown behaviour for each Test execution (or once for all the Tests).
1629
- **Runner**: a runner allow execution of a set of Suites and provide results
1730

18-
> CLove Unit tests discovery works parsing the symbol table in the test executable.
31+
> `CLove-Unit` tests discovery works parsing the symbol table in the test executable.
1932
>
2033
> At the moment this feature is available for the following OS / Architecture / Executable Format:
2134
> - Windows / 32-64 bit little-endian / PE (Portable Executable)
@@ -24,7 +37,6 @@ CLove Unit is implemented around the following concepts:
2437
>
2538
> Further compatibilities in terms of OS, Architecture and Format can be implement later on as needed.
2639
27-
2840
# Usage
2941
Just add [clove-unit.h](./clove-unit.h) header in your project and starts creating unit tests for your code base as follow:
3042

@@ -63,15 +75,23 @@ CLOVE_RUNNER()
6375
> - assertion usage ([test_suite1.c](./examples/clove101/test_suite1.c))
6476
> - suite setup & tear down ([test_suite2.c](./examples/clove101/test_suite2.c))
6577
66-
# Apis
67-
Here a list of availables "public" apis.
78+
# Development Apis
79+
Here a list of availables apis to support test development.
80+
81+
## Library Configuration
82+
Apis to be used for the very base setup of the library.
83+
84+
| Api | Description |
85+
| ------------- | ------------- |
86+
| CLOVE_IMPLEMENTATION | macro to be declared just once before `clove-unit.h` will include whole library implementation |
87+
| CLOVE_RUNNER() | generate program entry point |
88+
89+
6890
## Test Definition
6991
Apis to be used for defining suite and tests.
7092

7193
| Api | Description |
7294
| ------------- | ------------- |
73-
| CLOVE_IMPLEMENTATION | to be declared just once before `clove-unit.h` will include whole library implementation |
74-
| CLOVE_RUNNER() | generate program entry point |
7595
| CLOVE_SUITE_NAME | Macro to be defined for each suite, before including clove header |
7696
| CLOVE_SUITE_SETUP_ONCE() | Implement a procedure to be executed only once before all the test cases (Optional) |
7797
| CLOVE_SUITE_TEARDOWN_ONCE() | Implement a procedure to be executed only once after all the test cases (Optional) |
@@ -80,7 +100,7 @@ Apis to be used for defining suite and tests.
80100
| CLOVE_TEST(name) | Define test case named "name" |
81101

82102
## Test Assertions
83-
Assertions that can be used within a ```CLOVE_TEST```.
103+
Assertions that can be used within a ```CLOVE_TEST``` definition.
84104

85105
| Api | Description |
86106
| ------------- | ------------- |
@@ -89,34 +109,63 @@ Assertions that can be used within a ```CLOVE_TEST```.
89109
| CLOVE_IS_TRUE(result) | Check if int is not 0 |
90110
| CLOVE_IS_FALSE(result) | Check if int is 0 |
91111
| CLOVE_CHAR_EQ(expected, result) | Check equality between char |
92-
| CLOVE_CHAR_NE(expected, result) | Check inequaliy between char |
112+
| CLOVE_CHAR_NE(expected, result) | Check inequality between char |
93113
| CLOVE_INT_EQ(expected, result) | Check equality between int |
94-
| CLOVE_INT_NE(expected, result) | Check inequaliy between int |
114+
| CLOVE_INT_NE(expected, result) | Check inequality between int |
95115
| CLOVE_UINT_EQ(expected, result) | Check equality between unsigned int |
96-
| CLOVE_UINT_NE(expected, result) | Check inequaliy between unsigned int |
116+
| CLOVE_UINT_NE(expected, result) | Check inequality between unsigned int |
97117
| CLOVE_LONG_EQ(expected, result) | Check equality between long |
98-
| CLOVE_LONG_NE(expected, result) | Check inequaliy between long |
118+
| CLOVE_LONG_NE(expected, result) | Check inequality between long |
99119
| CLOVE_ULONG_EQ(expected, result) | Check equality between unsigned long |
100-
| CLOVE_ULONG_NE(expected, result) | Check inequaliy between unsigned long |
120+
| CLOVE_ULONG_NE(expected, result) | Check inequality between unsigned long |
101121
| CLOVE_LLONG_EQ(expected, result) | Check equality between long long |
102-
| CLOVE_LLONG_NE(expected, result) | Check inequaliy between long long |
122+
| CLOVE_LLONG_NE(expected, result) | Check inequality between long long |
103123
| CLOVE_ULLONG_EQ(expected, result) | Check equality between unsigned long long |
104-
| CLOVE_ULLONG_NE(expected, result) | Check inequaliy between unsigned long long |
124+
| CLOVE_ULLONG_NE(expected, result) | Check inequality between unsigned long long |
105125
| CLOVE_FLOAT_EQ(expected, result) | Check equality between float |
106-
| CLOVE_FLOAT_NE(expected, result) | Check inequaliy between float |
126+
| CLOVE_FLOAT_NE(expected, result) | Check inequality between float |
107127
| CLOVE_DOUBLE_EQ(expected, result) | Check equality between double |
108-
| CLOVE_DOUBLE_NE(expected, result) | Check inequaliy between double |
128+
| CLOVE_DOUBLE_NE(expected, result) | Check inequality between double |
109129
| CLOVE_STRING_EQ(expected, result) | Check equality between string (null terminated char pointer or array) |
110-
| CLOVE_STRING_NE(expected, result) | Check inequaliy between string (null terminated char pointer or array) |
130+
| CLOVE_STRING_NE(expected, result) | Check inequality between string (null terminated char pointer or array) |
111131
| CLOVE_NULL(result) | Check if result is NULL |
112132
| CLOVE_NOT_NULL(result) | Check if result is not NULL |
113133
| CLOVE_PTR_EQ(expected, result) | Check equality between pointers |
114-
| CLOVE_PTR_NE(expected, result) | Check inequaliy between pointers |
134+
| CLOVE_PTR_NE(expected, result) | Check inequality between pointers |
115135

116136

117137
## Test Helper
118138
Helper apis to support test implementation
119139
| Api | Description |
120140
| ------------- | ------------- |
121-
| CLOVE_EXEC_PATH() | Macro to easily retrive executable path |
122-
| CLOVE_EXEC_BASE_PATH() | Macro to easily retrive executable base path |
141+
| CLOVE_EXEC_PATH() | Macro to easily retrive executable path as a char* |
142+
| CLOVE_EXEC_BASE_PATH() | Macro to easily retrive executable base path a char* |
143+
144+
# Console Apis
145+
Commandline options supported by the binary produced by a `CLove-Unit` test project compilation.
146+
147+
| Command line | Description |
148+
| ------------- | ------------- |
149+
| \<exec\> | Running executable with no args will produce a verbose console report |
150+
| \<exec\> -i `SELECT_PATTERN` | include tests to be executed by the runner <br /> (optional argument, can be repeated more than once) |
151+
| \<exec\> -e `SELECT_PATTERN` | exclude tests to be executed by the runner <br /> (optional argument, can be repeated more than once) |
152+
153+
> NOTE: If both -i and -e options are provided, the inclusion pattern always wins over the exclusion one.
154+
155+
The `SELECT_PATTERN` works as follow:
156+
* Basic: `SuiteName.TestName`
157+
* Wildcard: Only `*` is supported, and can be used to implement pattern such as "start with", "end with", "contains", "all", for both the SuiteName and TestName
158+
159+
So for instance the following are valids select patterns (non-exhaustive list):
160+
| Pattern Example | Description |
161+
| ------------- | ------------- |
162+
| MySuite01.Test01 | will match exactly the Suite Name and the Test Name |
163+
| MySuite01 | will match all tests whose Suite Name is "MySuite01" |
164+
| Suite\* | will match all tests whose Suite Name starts with "Suite" |
165+
| \*Suite01: | will match all tests whose Suite Name ends with "Suite01" |
166+
| \*Suite\* | will match all tests whose Suite Name contains "Suite" |
167+
| \*Suite\* | will match all tests whose Suite Name contains "Suite" |
168+
| MySuite01.*01 | will match all tests whose Suite Name is MySuite01 and Test Name ends with "01" |
169+
| \*.\* | will match all suites and tests |
170+
171+

0 commit comments

Comments
 (0)