Debian Codegraph @

cross-project-tests/debuginfo-tests/dexter/Commands.md

raw
1 # Dexter commands
2
3 * [DexExpectProgramState](Commands.md#DexExpectProgramState)
4 * [DexExpectStepKind](Commands.md#DexExpectStepKind)
5 * [DexExpectStepOrder](Commands.md#DexExpectStepOrder)
6 * [DexExpectWatchType](Commands.md#DexExpectWatchType)
7 * [DexExpectWatchValue](Commands.md#DexExpectWatchValue)
8 * [DexUnreachable](Commands.md#DexUnreachable)
9 * [DexLimitSteps](Commands.md#DexLimitSteps)
10 * [DexLabel](Commands.md#DexLabel)
11 * [DexWatch](Commands.md#DexWatch)
12 * [DexDeclareAddress](Commands.md#DexDeclareAddress)
13 * [DexDeclareFile](Commands.md#DexDeclareFile)
14 * [DexFinishTest](Commands.md#DexFinishTest)
15 * [DexCommandLine](Commands.md#DexCommandLine)
16 * [DexStepFunction](Commands.md#DexStepFunction)
17 * [DexContinue](Commands.md#DexContinue)
18 ---
19 ## DexExpectProgramState
20 DexExpectProgramState(state [,**times])
21
22 Args:
23 state (dict): { 'frames': [
24 {
25 # StackFrame #
26 'function': name (str),
27 'is_inlined': bool,
28 'location': {
29 # SourceLocation #
30 'lineno': int,
31 'path': str,
32 'column': int,
33 },
34 'watches': {
35 expr (str): value (str),
36 expr (str): {
37 'value': str,
38 'type_name': str,
39 'could_evaluate': bool,
40 'is_optimized_away': bool,
41 'is_irretrievable': bool,
42 }
43 },
44 }
45 ]}
46
47 Keyword args:
48 times (int): Minimum number of times this state pattern is expected to
49 be seen. Defaults to 1. Can be 0.
50
51 ### Description
52 Expect to see a given program `state` a certain number of `times`.
53
54 For every debugger step the reported state is compared with the expected state.
55 To consider the states a match:
56
57 * The `SourceLocation` must match in both states. Omitted fields in the
58 `SourceLocation` dictionary are ignored; they always match.
59 * Each `expr` in `watches` in the expected state can either be a dictionary
60 with the fields shown above, or a string representing its value. In either
61 case, the actual value of `expr` in the debugger must match.
62 * The function name and inline status are not considered.
63
64 ### Heuristic
65 [TODO]
66
67
68 ---
69 ## DexExpectStepKind
70 DexExpectStepKind(kind, times)
71
72 Args:
73 kind (str): Expected step kind.
74 times (int): Expected number of encounters.
75
76 ### Description
77 Expect to see a particular step `kind` a number of `times` while stepping
78 through the program.
79
80 `kind` must be one of:
81
82 `FUNC`: The first step into a function which is defined in the test
83 directory.</br>
84 `FUNC_EXTERNAL`: A step over a function which is not defined in the test
85 directory.</br>
86 `FUNC_UNKNOWN`: The first step over a function an unknown definition
87 location.</br>
88 `VERTICAL_FORWARD`: A step onto a line after the previous step line in this
89 frame.</br>
90 `VERTICAL_BACKWARD`: A step onto a line before the previous step line in
91 this frame.</br>
92 `HORIZONTAL_FORWARD`: A step forward on the same line as the previous step in
93 this frame.</br>
94 `HORIZONTAL_BACKWARD`: A step backward on the same line as the previous step
95 in this frame.</br>
96 `SAME`: A step onto the same line and column as the previous step in this
97 frame.</br>
98
99 ### Heuristic
100 [TODO]
101
102
103 ---
104 ## DexExpectStepOrder
105 DexExpectStepOrder(*order [,**on_line])
106
107 Arg list:
108 order (int): One or more indices.
109
110 Keyword args:
111 on_line (int): Expect this line to be stepped on in the order given.
112
113 ### Description
114 Expect the line every `DexExpectStepOrder` is found on, or given from `on_line`, to be stepped on in
115 `order`. Each instance must have a set of unique ascending indices.
116
117 ### Heuristic
118 [TODO]
119
120
121 ---
122 ## DexExpectWatchType
123 DexExpectWatchType(expr, *types [,**from_line=1][,**to_line=Max]
124 [,**on_line][,**require_in_order=True])
125
126 Args:
127 expr (str): expression to evaluate.
128
129 Arg list:
130 types (str): At least one expected type. NOTE: string type.
131
132 Keyword args:
133 from_line (int): Evaluate the expression from this line. Defaults to 1.
134 to_line (int): Evaluate the expression to this line. Defaults to end of
135 source.
136 on_line (int): Only evaluate the expression on this line. If provided,
137 this overrides from_line and to_line.
138 require_in_order (bool): If False the values can appear in any order.
139
140 ### Description
141 Expect the expression `expr` to evaluate be evaluated and have each evaluation's
142 type checked against the list of `types`
143
144 ### Heuristic
145 [TODO]
146
147
148 ---
149 ## DexExpectWatchValue
150 DexExpectWatchValue(expr, *values [,**from_line=1][,**to_line=Max]
151 [,**on_line][,**require_in_order=True][,**float_range])
152
153 Args:
154 expr (str): expression to evaluate.
155
156 Arg list:
157 values (str): At least one expected value. NOTE: string type.
158
159 Keyword args:
160 from_line (int): Evaluate the expression from this line. Defaults to 1.
161 to_line (int): Evaluate the expression to this line. Defaults to end of
162 source.
163 on_line (int): Only evaluate the expression on this line. If provided,
164 this overrides from_line and to_line.
165 require_in_order (bool): If False the values can appear in any order.
166 float_range (float): If provided, `values` must be floats, and will
167 match an actual value if they are within `float_range` of each other.
168
169
170 ### Description
171 Expect the expression `expr` to evaluate to the list of `values`
172 sequentially.
173
174 ### Heuristic
175 [TODO]
176
177
178 ---
179 ## DexUnreachable
180 DexUnreachable([, **from_line=1][,**to_line=Max][,**on_line])
181
182 ### Description
183 Expect the source line this is found on will never be stepped on to. If either
184 'on_line' or both 'from_line' and 'to_line' are specified, checks that the
185 specified line(s) are not stepped on.
186
187 ### Heuristic
188 [TODO]
189
190
191 ----
192 ## DexLimitSteps
193 DexLimitSteps([expr, *values][, **from_line=1][,**to_line=Max]
194 [,**on_line][,**hit_count])
195
196 Args:
197 expr (str): variable or value to compare.
198
199 Arg list:
200 values (str): At least one potential value the expr may evaluate to.
201
202 Keyword args:
203 from_line (int): Define the start of the limited step range.
204 to_line (int): Define the end of the limited step range.
205 on_line (int): Define a range with length 1 starting and ending on the
206 same line.
207 hit_count (int): If provided, limit the number of times the command
208 triggers.
209
210 ### Description
211 Define a limited stepping range that may be predicated on a condition. When the
212 leading line is stepped on and any condition '(expr) == (values[n])' is true or
213 there are no conditions, set a range of temporary breakpoints within the test
214 file defined by the range 'from_line' and 'to_line' or 'on_line'. This only
215 happens 'hit_count' number of times if the argument is provided.
216
217 The condition is only evaluated on the line 'from_line' or 'on_line'. If the
218 condition is not true at the start of the range, or that line is never stepped
219 onto, the whole range is ignored.
220
221 DexLimitSteps commands are useful for reducing the amount of steps gathered in
222 large test cases that would normally take much longer to complete.
223
224 ----
225 ## DexLabel
226 DexLabel(name [, **on_line])
227
228 Args:
229 name (str): A unique name for this line.
230
231 Keyword args:
232 on_line (int): Specify a line number to label.
233
234 ### Description
235 Name the line this command is found on or 'on_line' if it is provided. Line
236 names can be converted to line numbers with the `ref(str)` function. For
237 example, `DexExpectWatchValues(..., on_line=ref('my_line_name'))`. Use
238 arithmetic operators to get offsets from labels:
239
240 DexExpectWatchValues(..., on_line=ref('my_line_name') + 3)
241 DexExpectWatchValues(..., on_line=ref('my_line_name') - 5)
242
243
244 ### Heuristic
245 This command does not contribute to the heuristic score.
246
247 ----
248 ## DexDeclareAddress
249 DexDeclareAddress(declared_address, expr, **on_line[, **hit_count])
250
251 Args:
252 declared_address (str): The unique name of an address, which can be used
253 in DexExpectWatch-commands.
254 expr (str): An expression to evaluate to provide the value of this
255 address.
256 on_line (int): The line at which the value of the expression will be
257 assigned to the address.
258 hit_count (int): If provided, reads the value of the source expression
259 after the line has been stepped onto the given number
260 of times ('hit_count = 0' gives default behaviour).
261
262 ### Description
263 Declares a variable that can be used in DexExpectWatch- commands as an expected
264 value by using the `address(str[, int])` function. This is primarily
265 useful for checking the values of pointer variables, which are generally
266 determined at run-time (and so cannot be consistently matched by a hard-coded
267 expected value), but may be consistent relative to each other. An example use of
268 this command is as follows, using a set of pointer variables "foo", "bar", and
269 "baz":
270
271 DexDeclareAddress('my_addr', 'bar', on_line=12)
272 DexExpectWatchValue('foo', address('my_addr'), on_line=10)
273 DexExpectWatchValue('bar', address('my_addr'), on_line=12)
274 DexExpectWatchValue('baz', address('my_addr', 16), on_line=14)
275
276 On the first line, we declare the name of our variable 'my_addr'. This name must
277 be unique (the same name cannot be declared twice), and attempting to reference
278 an undeclared variable with `address` will fail. The value of the address
279 variable will be assigned as the value of 'bar' when line 12 is first stepped
280 on.
281
282 On lines 2-4, we use the `address` function to refer to our variable. The first
283 usage occurs on line 10, before the line where 'my_addr' is assigned its value;
284 this is a valid use, as we assign the address value and check for correctness
285 after gathering all debug information for the test. Thus the first test command
286 will pass if 'foo' on line 10 has the same value as 'bar' on line 12.
287
288 The second command will pass iff 'bar' is available at line 12 - even if the
289 variable and lines are identical in DexDeclareAddress and DexExpectWatchValue,
290 the latter will still expect a valid value. Similarly, if the variable for a
291 DexDeclareAddress command is not available at the given line, any test against
292 that address will fail.
293
294 The `address` function also accepts an optional integer argument representing an
295 offset (which may be negative) to be applied to the address value, so
296 `address('my_addr', 16)` resolves to `my_addr + 16`. In the above example, this
297 means that we expect `baz == bar + 16`.
298
299 ### Heuristic
300 This command does not contribute to the heuristic score.
301
302 ----
303 ## DexDeclareFile
304 DexDeclareFile(declared_file)
305
306 Args:
307 name (str): A declared file path for which all subsequent commands
308 will have their path attribute set too.
309
310 ### Description
311 Set the path attribute of all commands from this point in the test onwards.
312 The new path holds until the end of the test file or until a new DexDeclareFile
313 command is encountered. Used in conjunction with .dex files, DexDeclareFile can
314 be used to write your dexter commands in a separate test file avoiding inlined
315 Dexter commands mixed with test source.
316
317 ### Heuristic
318 This command does not contribute to the heuristic score.
319
320 ----
321 ## DexFinishTest
322 DexFinishTest([expr, *values], **on_line[, **hit_count=0])
323
324 Args:
325 expr (str): variable or value to compare.
326
327 Arg list:
328 values (str): At least one potential value the expr may evaluate to.
329
330 Keyword args:
331 on_line (int): Define the line on which this command will be triggered.
332 hit_count (int): If provided, triggers this command only after the line
333 and condition have been hit the given number of times.
334
335 ### Description
336 Defines a point at which Dexter will exit out of the debugger without waiting
337 for the program to finish. This is primarily useful for testing a program that
338 either does not automatically terminate or would otherwise continue for a long
339 time after all test commands have finished.
340
341 The command will trigger when the line 'on_line' is stepped on and either the
342 condition '(expr) == (values[n])' is true or there are no conditions. If the
343 optional argument 'hit_count' is provided, then the command will not trigger
344 for the first 'hit_count' times the line and condition are hit.
345
346 ### Heuristic
347 This command does not contribute to the heuristic score.
348
349 ----
350 ## DexCommandLine
351 DexCommandLine(command_line)
352
353 Args:
354 command_line (list): List of strings that form the command line.
355
356 ### Description
357 Specifies the command line with which to launch the test. The arguments will
358 be appended to the default command line, i.e. the path to the compiled binary,
359 and will be passed to the program under test.
360
361 This command does not contribute to any part of the debug experience testing or
362 runtime instrumentation -- it's only for communicating arguments to the program
363 under test.
364
365 ### Heuristic
366 This command does not contribute to the heuristic score.
367
368 ---
369 ## DexWatch
370 DexWatch(*expressions)
371
372 Arg list:
373 expressions (str): `expression` to evaluate on this line.
374
375 ### Description
376 [Deprecated] Evaluate each given `expression` when the debugger steps onto the
377 line this command is found on.
378
379 ### Heuristic
380 [Deprecated]
381
382
383 ---
384 ## DexStepFunction
385 DexStepFunction(function_name[, **hit_count=0])
386
387 Arg list:
388 function_name (str): function to step through.
389 hit_count (int): If provided, limit the number of times the command
390 triggers.
391
392 ### Description
393 NOTE: Only supported for DAP-based debuggers.
394
395 This command controls stepping behaviour: Tell dexter to set a function
396 breakpoint and step through the function after hitting it. Composes well with
397 itself (you can may a callstack with multiple targets to step through) and
398 `DexContinue`.
399
400 ---
401 ## DexContinue
402 DexContinue(*[expr, *values], **from_line[, **to_line, **hit_count])
403
404 Arg list:
405 function_name (str): function to step through.
406 hit_count (int): If provided, limit the number of times the command
407 triggers.
408
409 ### Description
410 NOTE: Only supported for DAP-based debuggers.
411
412 This command controls stepping behaviour: Tell dexter to set a breakpoint on
413 `from_line`. When it is hit and optionally '(expr) == (values[n])' is true,
414 optionally set a breakpoint on `to_line`. Then 'continue' (tell the debugger to
415 run freely until a breakpoint is hit). Composed with `DexStepFunction` this
416 lets you avoid stepping over certain regions (many loop iterations, for
417 example). Continue-ing off the end of a `DexStepFunction` is well defined;
418 stepping will resume in `DexStepFunction` targets deeper in the callstack.
419
420 FIXME: hit_count should probably be inverted, like `DexLimitSteps`, to trigger
421 AFTER that many hits?