03c45f14bf
DexExpectStepOrder uses the line to expect a debugger step from the actual line of the command in the Dexter source file. Now Dexter scripts have mainly moved to thier own script files instead of the actual source, there should be a option to override this behaviour to choose your own debugger step location. Reviewed By: Orlando Differential Revision: https://reviews.llvm.org/D142099
380 lines
13 KiB
Markdown
380 lines
13 KiB
Markdown
# Dexter commands
|
|
|
|
* [DexExpectProgramState](Commands.md#DexExpectProgramState)
|
|
* [DexExpectStepKind](Commands.md#DexExpectStepKind)
|
|
* [DexExpectStepOrder](Commands.md#DexExpectStepOrder)
|
|
* [DexExpectWatchType](Commands.md#DexExpectWatchType)
|
|
* [DexExpectWatchValue](Commands.md#DexExpectWatchValue)
|
|
* [DexUnreachable](Commands.md#DexUnreachable)
|
|
* [DexLimitSteps](Commands.md#DexLimitSteps)
|
|
* [DexLabel](Commands.md#DexLabel)
|
|
* [DexWatch](Commands.md#DexWatch)
|
|
* [DexDeclareAddress](Commands.md#DexDeclareAddress)
|
|
* [DexDeclareFile](Commands.md#DexDeclareFile)
|
|
* [DexFinishTest](Commands.md#DexFinishTest)
|
|
* [DexCommandLine](Commands.md#DexCommandLine)
|
|
|
|
---
|
|
## DexExpectProgramState
|
|
DexExpectProgramState(state [,**times])
|
|
|
|
Args:
|
|
state (dict): { 'frames': [
|
|
{
|
|
# StackFrame #
|
|
'function': name (str),
|
|
'is_inlined': bool,
|
|
'location': {
|
|
# SourceLocation #
|
|
'lineno': int,
|
|
'path': str,
|
|
'column': int,
|
|
},
|
|
'watches': {
|
|
expr (str): value (str),
|
|
expr (str): {
|
|
'value': str,
|
|
'type_name': str,
|
|
'could_evaluate': bool,
|
|
'is_optimized_away': bool,
|
|
'is_irretrievable': bool,
|
|
}
|
|
},
|
|
}
|
|
]}
|
|
|
|
Keyword args:
|
|
times (int): Minimum number of times this state pattern is expected to
|
|
be seen. Defaults to 1. Can be 0.
|
|
|
|
### Description
|
|
Expect to see a given program `state` a certain number of `times`.
|
|
|
|
For every debugger step the reported state is compared with the expected state.
|
|
To consider the states a match:
|
|
|
|
* The `SourceLocation` must match in both states. Omitted fields in the
|
|
`SourceLocation` dictionary are ignored; they always match.
|
|
* Each `expr` in `watches` in the expected state can either be a dictionary
|
|
with the fields shown above, or a string representing its value. In either
|
|
case, the actual value of `expr` in the debugger must match.
|
|
* The function name and inline status are not considered.
|
|
|
|
### Heuristic
|
|
[TODO]
|
|
|
|
|
|
---
|
|
## DexExpectStepKind
|
|
DexExpectStepKind(kind, times)
|
|
|
|
Args:
|
|
kind (str): Expected step kind.
|
|
times (int): Expected number of encounters.
|
|
|
|
### Description
|
|
Expect to see a particular step `kind` a number of `times` while stepping
|
|
through the program.
|
|
|
|
`kind` must be one of:
|
|
|
|
`FUNC`: The first step into a function which is defined in the test
|
|
directory.</br>
|
|
`FUNC_EXTERNAL`: A step over a function which is not defined in the test
|
|
directory.</br>
|
|
`FUNC_UNKNOWN`: The first step over a function an unknown definition
|
|
location.</br>
|
|
`VERTICAL_FORWARD`: A step onto a line after the previous step line in this
|
|
frame.</br>
|
|
`VERTICAL_BACKWARD`: A step onto a line before the previous step line in
|
|
this frame.</br>
|
|
`HORIZONTAL_FORWARD`: A step forward on the same line as the previous step in
|
|
this frame.</br>
|
|
`HORIZONTAL_BACKWARD`: A step backward on the same line as the previous step
|
|
in this frame.</br>
|
|
`SAME`: A step onto the same line and column as the previous step in this
|
|
frame.</br>
|
|
|
|
### Heuristic
|
|
[TODO]
|
|
|
|
|
|
---
|
|
## DexExpectStepOrder
|
|
DexExpectStepOrder(*order [,**on_line])
|
|
|
|
Arg list:
|
|
order (int): One or more indices.
|
|
|
|
Keyword args:
|
|
on_line (int): Expect this line to be stepped on in the order given.
|
|
|
|
### Description
|
|
Expect the line every `DexExpectStepOrder` is found on, or given from `on_line`, to be stepped on in
|
|
`order`. Each instance must have a set of unique ascending indices.
|
|
|
|
### Heuristic
|
|
[TODO]
|
|
|
|
|
|
---
|
|
## DexExpectWatchType
|
|
DexExpectWatchType(expr, *types [,**from_line=1][,**to_line=Max]
|
|
[,**on_line][,**require_in_order=True])
|
|
|
|
Args:
|
|
expr (str): expression to evaluate.
|
|
|
|
Arg list:
|
|
types (str): At least one expected type. NOTE: string type.
|
|
|
|
Keyword args:
|
|
from_line (int): Evaluate the expression from this line. Defaults to 1.
|
|
to_line (int): Evaluate the expression to this line. Defaults to end of
|
|
source.
|
|
on_line (int): Only evaluate the expression on this line. If provided,
|
|
this overrides from_line and to_line.
|
|
require_in_order (bool): If False the values can appear in any order.
|
|
|
|
### Description
|
|
Expect the expression `expr` to evaluate be evaluated and have each evaluation's
|
|
type checked against the list of `types`
|
|
|
|
### Heuristic
|
|
[TODO]
|
|
|
|
|
|
---
|
|
## DexExpectWatchValue
|
|
DexExpectWatchValue(expr, *values [,**from_line=1][,**to_line=Max]
|
|
[,**on_line][,**require_in_order=True][,**float_range])
|
|
|
|
Args:
|
|
expr (str): expression to evaluate.
|
|
|
|
Arg list:
|
|
values (str): At least one expected value. NOTE: string type.
|
|
|
|
Keyword args:
|
|
from_line (int): Evaluate the expression from this line. Defaults to 1.
|
|
to_line (int): Evaluate the expression to this line. Defaults to end of
|
|
source.
|
|
on_line (int): Only evaluate the expression on this line. If provided,
|
|
this overrides from_line and to_line.
|
|
require_in_order (bool): If False the values can appear in any order.
|
|
float_range (float): If provided, `values` must be floats, and will
|
|
match an actual value if they are within `float_range` of each other.
|
|
|
|
|
|
### Description
|
|
Expect the expression `expr` to evaluate to the list of `values`
|
|
sequentially.
|
|
|
|
### Heuristic
|
|
[TODO]
|
|
|
|
|
|
---
|
|
## DexUnreachable
|
|
DexUnreachable([, **from_line=1][,**to_line=Max][,**on_line])
|
|
|
|
### Description
|
|
Expect the source line this is found on will never be stepped on to. If either
|
|
'on_line' or both 'from_line' and 'to_line' are specified, checks that the
|
|
specified line(s) are not stepped on.
|
|
|
|
### Heuristic
|
|
[TODO]
|
|
|
|
|
|
----
|
|
## DexLimitSteps
|
|
DexLimitSteps([expr, *values][, **from_line=1][,**to_line=Max]
|
|
[,**on_line][,**hit_count])
|
|
|
|
Args:
|
|
expr (str): variable or value to compare.
|
|
|
|
Arg list:
|
|
values (str): At least one potential value the expr may evaluate to.
|
|
|
|
Keyword args:
|
|
from_line (int): Define the start of the limited step range.
|
|
to_line (int): Define the end of the limited step range.
|
|
on_line (int): Define a range with length 1 starting and ending on the
|
|
same line.
|
|
hit_count (int): If provided, limit the number of times the command
|
|
triggers.
|
|
|
|
### Description
|
|
Define a limited stepping range that may be predicated on a condition. When the
|
|
leading line is stepped on and any condition '(expr) == (values[n])' is true or
|
|
there are no conditions, set a range of temporary breakpoints within the test
|
|
file defined by the range 'from_line' and 'to_line' or 'on_line'. This only
|
|
happens 'hit_count' number of times if the argument is provided.
|
|
|
|
The condition is only evaluated on the line 'from_line' or 'on_line'. If the
|
|
condition is not true at the start of the range, or that line is never stepped
|
|
onto, the whole range is ignored.
|
|
|
|
DexLimitSteps commands are useful for reducing the amount of steps gathered in
|
|
large test cases that would normally take much longer to complete.
|
|
|
|
----
|
|
## DexLabel
|
|
DexLabel(name [, **on_line])
|
|
|
|
Args:
|
|
name (str): A unique name for this line.
|
|
|
|
Keyword args:
|
|
on_line (int): Specify a line number to label.
|
|
|
|
### Description
|
|
Name the line this command is found on or 'on_line' if it is provided. Line
|
|
names can be converted to line numbers with the `ref(str)` function. For
|
|
example, `DexExpectWatchValues(..., on_line=ref('my_line_name'))`. Use
|
|
arithmetic operators to get offsets from labels:
|
|
|
|
DexExpectWatchValues(..., on_line=ref('my_line_name') + 3)
|
|
DexExpectWatchValues(..., on_line=ref('my_line_name') - 5)
|
|
|
|
|
|
### Heuristic
|
|
This command does not contribute to the heuristic score.
|
|
|
|
----
|
|
## DexDeclareAddress
|
|
DexDeclareAddress(declared_address, expr, **on_line[, **hit_count])
|
|
|
|
Args:
|
|
declared_address (str): The unique name of an address, which can be used
|
|
in DexExpectWatch-commands.
|
|
expr (str): An expression to evaluate to provide the value of this
|
|
address.
|
|
on_line (int): The line at which the value of the expression will be
|
|
assigned to the address.
|
|
hit_count (int): If provided, reads the value of the source expression
|
|
after the line has been stepped onto the given number
|
|
of times ('hit_count = 0' gives default behaviour).
|
|
|
|
### Description
|
|
Declares a variable that can be used in DexExpectWatch- commands as an expected
|
|
value by using the `address(str[, int])` function. This is primarily
|
|
useful for checking the values of pointer variables, which are generally
|
|
determined at run-time (and so cannot be consistently matched by a hard-coded
|
|
expected value), but may be consistent relative to each other. An example use of
|
|
this command is as follows, using a set of pointer variables "foo", "bar", and
|
|
"baz":
|
|
|
|
DexDeclareAddress('my_addr', 'bar', on_line=12)
|
|
DexExpectWatchValue('foo', address('my_addr'), on_line=10)
|
|
DexExpectWatchValue('bar', address('my_addr'), on_line=12)
|
|
DexExpectWatchValue('baz', address('my_addr', 16), on_line=14)
|
|
|
|
On the first line, we declare the name of our variable 'my_addr'. This name must
|
|
be unique (the same name cannot be declared twice), and attempting to reference
|
|
an undeclared variable with `address` will fail. The value of the address
|
|
variable will be assigned as the value of 'bar' when line 12 is first stepped
|
|
on.
|
|
|
|
On lines 2-4, we use the `address` function to refer to our variable. The first
|
|
usage occurs on line 10, before the line where 'my_addr' is assigned its value;
|
|
this is a valid use, as we assign the address value and check for correctness
|
|
after gathering all debug information for the test. Thus the first test command
|
|
will pass if 'foo' on line 10 has the same value as 'bar' on line 12.
|
|
|
|
The second command will pass iff 'bar' is available at line 12 - even if the
|
|
variable and lines are identical in DexDeclareAddress and DexExpectWatchValue,
|
|
the latter will still expect a valid value. Similarly, if the variable for a
|
|
DexDeclareAddress command is not available at the given line, any test against
|
|
that address will fail.
|
|
|
|
The `address` function also accepts an optional integer argument representing an
|
|
offset (which may be negative) to be applied to the address value, so
|
|
`address('my_addr', 16)` resolves to `my_addr + 16`. In the above example, this
|
|
means that we expect `baz == bar + 16`.
|
|
|
|
### Heuristic
|
|
This command does not contribute to the heuristic score.
|
|
|
|
----
|
|
## DexDeclareFile
|
|
DexDeclareFile(declared_file)
|
|
|
|
Args:
|
|
name (str): A declared file path for which all subsequent commands
|
|
will have their path attribute set too.
|
|
|
|
### Description
|
|
Set the path attribute of all commands from this point in the test onwards.
|
|
The new path holds until the end of the test file or until a new DexDeclareFile
|
|
command is encountered. Used in conjunction with .dex files, DexDeclareFile can
|
|
be used to write your dexter commands in a separate test file avoiding inlined
|
|
Dexter commands mixed with test source.
|
|
|
|
### Heuristic
|
|
This command does not contribute to the heuristic score.
|
|
|
|
----
|
|
## DexFinishTest
|
|
DexFinishTest([expr, *values], **on_line[, **hit_count=0])
|
|
|
|
Args:
|
|
expr (str): variable or value to compare.
|
|
|
|
Arg list:
|
|
values (str): At least one potential value the expr may evaluate to.
|
|
|
|
Keyword args:
|
|
on_line (int): Define the line on which this command will be triggered.
|
|
hit_count (int): If provided, triggers this command only after the line
|
|
and condition have been hit the given number of times.
|
|
|
|
### Description
|
|
Defines a point at which Dexter will exit out of the debugger without waiting
|
|
for the program to finish. This is primarily useful for testing a program that
|
|
either does not automatically terminate or would otherwise continue for a long
|
|
time after all test commands have finished.
|
|
|
|
The command will trigger when the line 'on_line' is stepped on and either the
|
|
condition '(expr) == (values[n])' is true or there are no conditions. If the
|
|
optional argument 'hit_count' is provided, then the command will not trigger
|
|
for the first 'hit_count' times the line and condition are hit.
|
|
|
|
### Heuristic
|
|
This command does not contribute to the heuristic score.
|
|
|
|
----
|
|
## DexCommandLine
|
|
DexCommandLine(command_line)
|
|
|
|
Args:
|
|
command_line (list): List of strings that form the command line.
|
|
|
|
### Description
|
|
Specifies the command line with which to launch the test. The arguments will
|
|
be appended to the default command line, i.e. the path to the compiled binary,
|
|
and will be passed to the program under test.
|
|
|
|
This command does not contribute to any part of the debug experience testing or
|
|
runtime instrumentation -- it's only for communicating arguments to the program
|
|
under test.
|
|
|
|
### Heuristic
|
|
This command does not contribute to the heuristic score.
|
|
|
|
---
|
|
## DexWatch
|
|
DexWatch(*expressions)
|
|
|
|
Arg list:
|
|
expressions (str): `expression` to evaluate on this line.
|
|
|
|
### Description
|
|
[Deprecated] Evaluate each given `expression` when the debugger steps onto the
|
|
line this command is found on.
|
|
|
|
### Heuristic
|
|
[Deprecated]
|