cutter(1)

1CUTTER(1)                       Cutter's manual                      CUTTER(1)
2
3
4

NAME

6       cutter - xUnit family unit testing framework for C and C++
7

SYNOPSIS

9       cutter [option ...] test-directory
10
11       cutter --mode=analyze [option ...] log-directory
12

DESCRIPTION

14       Cutter  is  a xUnit family unit testing framework for C and C++. Cutter
15       provides programmers two important interfaces:
16
17       1.     easy to write API
18
19       2.     easy to debug UI
20
21       Cutter helps programmers to write their new tests, run  their  existing
22       tests, get feedbacks from ran their tests.
23
24       test-directory  is  a  directory  which  has  test_*.so.  test_*.so are
25       searched recursively.
26
27       log-directory is a directory which has Cutter log  files.  Cutter  logs
28       test results when --stream-directory option is specified.
29

OPTIONS

31       --version
32              Cutter shows its own version and exits.
33
34       --log-level=LEVEL
35              It sets log level to LEVEL.
36
37              LEVEL can be combined them with '|' like "error|warning".
38
39              You  can  add  a level to the default level by prepending "+" to
40              level like "+trace|+info".
41
42              You can remove a level from the default level by prepending  "-"
43              to level like "-error|-warning".
44
45              Here are available levels:
46
47              · default: equals to "critical|error|warning|message".
48
49              · none: logs nothing.
50
51              · critical: logs only critial information.
52
53              · error: logs only error information.
54
55              · warning: logs only warning information.
56
57              · message: logs only normal messages.
58
59              · info: logs only additional information.
60
61              · debug: logs only debug information.
62
63              · traces: logs only trace information.
64
65              · all: logs all log information.
66
67              The default is "default".
68
69       --mode=[test|analyze]
70              It  specifies run mode. Cutter runs tests when run mode is test.
71              Cutter analyzes test results when run mode is analyze.
72
73              The default is test.
74
75       -s DIRECTORY, --source-directory=DIRECTORY
76              Cutter prepends DIRECTORY to file name when test fails. This  is
77              for  tolls  (like  Emacs)  which  have function jumping to error
78              line.
79
80       -t TEST_CASE_NAME, --test-case=TEST_CASE_NAME
81              Cutter runs test cases that are matched with TEST_CASE_NAME.  If
82              TEST_CASE_NAME    is   surrounded   by   "/"   (e.g.   /test_/),
83              TEST_CASE_NAME is handled as regular expression.
84
85              This option can be specified n times. In the case,  Cutter  runs
86              test cases that are matched with any TEST_CASE_NAME. (OR)
87
88       -n TEST_NAME, --name=TEST_NAME
89              Cutter  runs tests that are matched with TEST_NAME. If TEST_NAME
90              is surrounded by "/" (e.g. /test_/),  TEST_NAME  is  handled  as
91              regular expression.
92
93              This  option  can be specified n times. In the case, Cutter runs
94              test that are matched with any TEST_NAME. (OR)
95
96       -m, --multi-thread
97              Cutter runs a test case in a new thread.
98
99              The default is off.
100
101       --max-threads=MAX_THREADS
102              Run test cases and iterated tests with MAX_THREADS threads  con‐
103              currently at a maximum. -1 means no limit.
104
105              The default is 10.
106
107       --disable-signal-handling
108              Disable signal handling that provides aborting test by C-c, pro‐
109              vides backtrace on SEGV and so on. If your test target uses sig‐
110              nal,  Cutter's signal handling may cause a problem. In the case,
111              you should disable Cutter's signal handling by this option.
112
113              The default is enabled.
114
115       --test-case-order=[none|name|name-desc]
116              It specifies test case order.
117
118              If 'none' is specified, Cutter doesn't sort. If 'name' is speci‐
119              fied,  Cutter  sorts  test  cases by name in ascending order. If
120              'name-desc' is specified, Cutter sorts test  cases  by  name  in
121              descending order.
122
123              The default is none.
124
125       --exclude-file=FILE
126              Cutter doesn't read FILE on test collecting.
127
128       --exclude-directory=DIRECTORY
129              Cutter doesn't search tests under DIRECTORY.
130
131       --fatal-failures
132              Cutter  treats  failures  as fatal problem. It means that Cutter
133              stops test run.
134
135              The default is off.
136
137       --keep-opening-modules
138              Cutter keeps opening  loaded  modules  to  resolve  symbols  for
139              debugging.
140
141              The default is off.
142
143       --enable-convenience-attribute-definition
144              It enables convenience but danger "#{ATTRIBUTE_NAME}_#{TEST_NAME
145              - 'test_' PREFIX}" attribute set function.
146
147              The default is off.
148
149       --stop-before-test
150              It sets a breakpoint immediately before each test. You can  dive
151              into test function easily by running cutter on your debugger and
152              stepping into the next function.
153
154              The default is off.
155
156       -u[console|gtk], --ui=[console|gtk]
157              It specifies UI.
158
159              The default is console UI.
160
161       -v[s|silent|n|normal|v|verbose],    --verbose=[s|silent|n|normal|v|ver‐
162       bose]
163              It specifies verbose level.
164
165              This option is only for console UI.
166
167       -c[yes|true|no|false|auto], --color=[yes|true|no|false|auto]
168              If 'yes' or 'true' is specified, Cutter uses colorized output by
169              escape sequence. If 'no' or 'false' is specified,  Cutter  never
170              use colorized output. If 'auto' or the option is omitted, Cutter
171              uses colorized output if available.
172
173              This option is only for console UI.
174
175       --pdf-report=FILE
176              Cutter outputs a test report to FILE as PDF format.
177
178       --xml-report=FILE
179              Cutter outputs a test report to FILE as XML format.
180
181       --stream=[xml]
182              It  specifies  stream  backend.  Stream  backend  streams   test
183              results.
184
185              There is only XML stream backend for now.
186
187       --stream-fd=FILE_DESCRIPTOR
188              It  specifies  output  file  descriptor.  The XML stream backend
189              streams to FILE_DESCRIPTOR.
190
191              This option is only for XML stream backend.
192
193       --stream-directory=DIRECTORY
194              It specifies output directory. The XML stream backend streams to
195              a file under DIRECTORY.
196
197              This option is only for XML stream backend.
198
199       -?, --help
200              Cutter shows common options.
201
202       --help-stream
203              Cutter shows stream related options.
204
205       --help-report
206              Cutter shows report related options.
207
208       --help-ui
209              Cutter shows UI related options.
210
211       --help-all
212              Cutter shows all options.
213

EXIT STATUS

215       The  exit  status  is  0  if  all tests are passed and non-0 otherwise.
216       Omission test result and notification test result are  not  treated  as
217       failure.
218

FILES

220       /usr/share/doc/cutter/
221              The directory has Cutter documents. e.g. reference manual, tuto‐
222              rial and so on.
223

EXAMPLE

225       In the following example, cutter runs tests under tests/ directory  and
226       shows test progress verbosely.
227           % cutter -v v test/
228
229       In the following example, test results are saved under logs/ directory:
230           % cutter --stream=xml --stream-directory=logs/ test/
231