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
13---
14## DexExpectProgramState
15    DexExpectProgramState(state [,**times])
16
17    Args:
18        state (dict): { 'frames': [
19                        {
20                          # StackFrame #
21                          'function': name (str),
22                          'is_inlined': bool,
23                          'location': {
24                            # SourceLocation #
25                            'lineno': int,
26                            'path': str,
27                            'column': int,
28                          },
29                          'watches': {
30                            expr (str): value (str),
31                            expr (str): {
32                              'value': str,
33                              'type_name': str,
34                              'could_evaluate': bool,
35                              'is_optimized_away': bool,
36                              'is_irretrievable': bool,
37			    }
38                          },
39                        }
40                      ]}
41
42    Keyword args:
43        times (int): Minimum number of times this state pattern is expected to
44             be seen. Defaults to 1. Can be 0.
45
46### Description
47Expect to see a given program `state` a certain number of `times`.
48
49For every debugger step the reported state is compared with the expected state.
50To consider the states a match:
51
52* The `SourceLocation` must match in both states. Omitted fields in the
53`SourceLocation` dictionary are ignored; they always match.
54* Each `expr` in `watches` in the expected state can either be a dictionary
55with the fields shown above, or a string representing its value. In either
56case, the actual value of `expr` in the debugger must match.
57* The function name and inline status are not considered.
58
59### Heuristic
60[TODO]
61
62
63---
64## DexExpectStepKind
65    DexExpectStepKind(kind, times)
66
67    Args:
68      kind (str): Expected step kind.
69      times (int): Expected number of encounters.
70
71### Description
72Expect to see a particular step `kind` a number of `times` while stepping
73through the program.
74
75`kind` must be one of:
76
77`FUNC`: The first step into a function which is defined in the test
78directory.</br>
79`FUNC_EXTERNAL`: A step over a function which is not defined in the test
80directory.</br>
81`FUNC_UNKNOWN`: The first step over a function an unknown definition
82location.</br>
83`VERTICAL_FORWARD`: A step onto a line after the previous step line in this
84frame.</br>
85`VERTICAL_BACKWARD`: A step onto a line before the previous step line in
86this frame.</br>
87`HORIZONTAL_FORWARD`: A step forward on the same line as the previous step in
88this frame.</br>
89`HORIZONTAL_BACKWARD`: A step backward on the same line as the previous step
90in this frame.</br>
91`SAME`: A step onto the same line and column as the previous step in this
92frame.</br>
93
94### Heuristic
95[TODO]
96
97
98---
99## DexExpectStepOrder
100    DexExpectStepOrder(*order)
101
102    Arg list:
103      order (int): One or more indices.
104
105### Description
106Expect the line every `DexExpectStepOrder` is found on to be stepped on in
107`order`. Each instance must have a set of unique ascending indices.
108
109### Heuristic
110[TODO]
111
112
113---
114## DexExpectWatchType
115    DexExpectWatchType(expr, *types [,**from_line=1][,**to_line=Max]
116                        [,**on_line][,**require_in_order=True])
117
118    Args:
119        expr (str): expression to evaluate.
120
121    Arg list:
122        types (str): At least one expected type. NOTE: string type.
123
124    Keyword args:
125        from_line (int): Evaluate the expression from this line. Defaults to 1.
126        to_line (int): Evaluate the expression to this line. Defaults to end of
127            source.
128        on_line (int): Only evaluate the expression on this line. If provided,
129            this overrides from_line and to_line.
130        require_in_order (bool): If False the values can appear in any order.
131
132### Description
133Expect the expression `expr` to evaluate be evaluated and have each evaluation's
134type checked against the list of `types`
135
136### Heuristic
137[TODO]
138
139
140---
141## DexExpectWatchValue
142    DexExpectWatchValue(expr, *values [,**from_line=1][,**to_line=Max]
143                        [,**on_line][,**require_in_order=True])
144
145    Args:
146        expr (str): expression to evaluate.
147
148    Arg list:
149        values (str): At least one expected value. NOTE: string type.
150
151    Keyword args:
152        from_line (int): Evaluate the expression from this line. Defaults to 1.
153        to_line (int): Evaluate the expression to this line. Defaults to end of
154            source.
155        on_line (int): Only evaluate the expression on this line. If provided,
156            this overrides from_line and to_line.
157        require_in_order (bool): If False the values can appear in any order.
158
159### Description
160Expect the expression `expr` to evaluate to the list of `values`
161sequentially.
162
163### Heuristic
164[TODO]
165
166
167---
168## DexUnreachable
169    DexUnreachable()
170
171### Description
172Expect the source line this is found on will never be stepped on to.
173
174### Heuristic
175[TODO]
176
177
178----
179## DexLimitSteps
180    DexLimitSteps(expr, *values [, **from_line=1],[,**to_line=Max]
181                  [,**on_line])
182
183    Args:
184        expr (str): variable or value to compare.
185
186    Arg list:
187        values (str): At least one potential value the expr may evaluate to.
188
189    Keyword args:
190        from_line (int): Define the start of the limited step range.
191        to_line (int): Define the end of the limited step range.
192        on_line (int): Define a range with length 1 starting and ending on the
193                       same line.
194
195### Description
196Define a limited stepping range that is predicated on a condition. When
197'(expr) == (values[n])', set a range of temporary, unconditional break points within
198the test file defined by the range from_line and to_line or on_line.
199
200The condition is only evaluated on the line 'from_line' or 'on_line'. If the
201condition is not true at the start of the range, the whole range is ignored.
202
203DexLimitSteps commands are useful for reducing the amount of steps gathered in
204large test cases that would normally take much longer to complete.
205
206----
207## DexLabel
208    DexLabel(name)
209
210    Args:
211        name (str): A unique name for this line.
212
213### Description
214Name the line this command is found on. Line names can be referenced by other
215commands expecting line number arguments.
216For example, `DexExpectWatchValues(..., on_line='my_line_name')`.
217
218### Heuristic
219This command does not contribute to the heuristic score.
220
221
222---
223## DexWatch
224    DexWatch(*expressions)
225
226    Arg list:
227        expressions (str): `expression` to evaluate on this line.
228
229### Description
230[Deprecated] Evaluate each given `expression` when the debugger steps onto the
231line this command is found on.
232
233### Heuristic
234[Deprecated]
235