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