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

   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
  51 Expect to see a given program `state` a certain number of `times`.
  52
  53 For every debugger step the reported state is compared with the expected state.
  54 To 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
  59 with the fields shown above, or a string representing its value. In either
  60 case, 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
  76 Expect to see a particular step `kind` a number of `times` while stepping
  77 through the program.
  78
  79 `kind` must be one of:
  80
  81 `FUNC`: The first step into a function which is defined in the test
  82 directory.</br>
  83 `FUNC_EXTERNAL`: A step over a function which is not defined in the test
  84 directory.</br>
  85 `FUNC_UNKNOWN`: The first step over a function an unknown definition
  86 location.</br>
  87 `VERTICAL_FORWARD`: A step onto a line after the previous step line in this
  88 frame.</br>
  89 `VERTICAL_BACKWARD`: A step onto a line before the previous step line in
  90 this frame.</br>
  91 `HORIZONTAL_FORWARD`: A step forward on the same line as the previous step in
  92 this frame.</br>
  93 `HORIZONTAL_BACKWARD`: A step backward on the same line as the previous step
  94 in this frame.</br>
  95 `SAME`: A step onto the same line and column as the previous step in this
  96 frame.</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
 113 Expect 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
 140 Expect the expression `expr` to evaluate be evaluated and have each evaluation's
 141 type 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
 170 Expect the expression `expr` to evaluate to the list of `values`
 171 sequentially.
 172
 173 ### Heuristic
 174 [TODO]
 175
 176
 177 ---
 178 ## DexUnreachable
 179     DexUnreachable([, **from_line=1][,**to_line=Max][,**on_line])
 180
 181 ### Description
 182 Expect 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
 184 specified 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
 210 Define a limited stepping range that may be predicated on a condition. When the
 211 leading line is stepped on and any condition '(expr) == (values[n])' is true or
 212 there are no conditions, set a range of temporary breakpoints within the test
 213 file defined by the range 'from_line' and 'to_line' or 'on_line'. This only
 214 happens 'hit_count' number of times if the argument is provided.
 215
 216 The condition is only evaluated on the line 'from_line' or 'on_line'. If the
 217 condition is not true at the start of the range, or that line is never stepped
 218 onto, the whole range is ignored.
 219
 220 DexLimitSteps commands are useful for reducing the amount of steps gathered in
 221 large 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
 234 Name the line this command is found on or 'on_line' if it is provided. Line
 235 names can be converted to line numbers with the `ref(str)` function. For
 236 example, `DexExpectWatchValues(..., on_line=ref('my_line_name'))`. Use
 237 arithmetic 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
 244 This 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
 262 Declares a variable that can be used in DexExpectWatch- commands as an expected
 263 value by using the `address(str[, int])` function. This is primarily
 264 useful for checking the values of pointer variables, which are generally
 265 determined at run-time (and so cannot be consistently matched by a hard-coded
 266 expected value), but may be consistent relative to each other. An example use of
 267 this 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
 275 On the first line, we declare the name of our variable 'my_addr'. This name must
 276 be unique (the same name cannot be declared twice), and attempting to reference
 277 an undeclared variable with `address` will fail. The value of the address
 278 variable will be assigned as the value of 'bar' when line 12 is first stepped
 279 on.
 280
 281 On lines 2-4, we use the `address` function to refer to our variable. The first
 282 usage occurs on line 10, before the line where 'my_addr' is assigned its value;
 283 this is a valid use, as we assign the address value and check for correctness
 284 after gathering all debug information for the test. Thus the first test command
 285 will pass if 'foo' on line 10 has the same value as 'bar' on line 12.
 286
 287 The second command will pass iff 'bar' is available at line 12 - even if the
 288 variable and lines are identical in DexDeclareAddress and DexExpectWatchValue,
 289 the latter will still expect a valid value. Similarly, if the variable for a
 290 DexDeclareAddress command is not available at the given line, any test against
 291 that address will fail.
 292
 293 The `address` function also accepts an optional integer argument representing an
 294 offset (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
 296 means that we expect `baz == bar + 16`.
 297
 298 ### Heuristic
 299 This 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
 310 Set the path attribute of all commands from this point in the test onwards.
 311 The new path holds until the end of the test file or until a new DexDeclareFile
 312 command is encountered. Used in conjunction with .dex files, DexDeclareFile can
 313 be used to write your dexter commands in a separate test file avoiding inlined
 314 Dexter commands mixed with test source.
 315
 316 ### Heuristic
 317 This 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
 335 Defines a point at which Dexter will exit out of the debugger without waiting
 336 for the program to finish. This is primarily useful for testing a program that
 337 either does not automatically terminate or would otherwise continue for a long
 338 time after all test commands have finished.
 339
 340 The command will trigger when the line 'on_line' is stepped on and either the
 341 condition '(expr) == (values[n])' is true or there are no conditions. If the
 342 optional argument 'hit_count' is provided, then the command will not trigger
 343 for the first 'hit_count' times the line and condition are hit.
 344
 345 ### Heuristic
 346 This 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
 356 Specifies the command line with which to launch the test. The arguments will
 357 be appended to the default command line, i.e. the path to the compiled binary,
 358 and will be passed to the program under test.
 359
 360 This command does not contribute to any part of the debug experience testing or
 361 runtime instrumentation -- it's only for communicating arguments to the program
 362 under test.
 363
 364 ### Heuristic
 365 This 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
 376 line this command is found on.
 377
 378 ### Heuristic
 379 [Deprecated]