1"""
2Test some lldb help commands.
3
4See also CommandInterpreter::OutputFormattedHelpText().
5"""
6
7
8
9import os
10import lldb
11from lldbsuite.test.decorators import *
12from lldbsuite.test.lldbtest import *
13from lldbsuite.test import lldbutil
14
15
16class HelpCommandTestCase(TestBase):
17
18    mydir = TestBase.compute_mydir(__file__)
19
20    @no_debug_info_test
21    def test_simplehelp(self):
22        """A simple test of 'help' command and its output."""
23        self.expect("help",
24                    startstr='Debugger commands:')
25
26        self.expect("help -a", matching=False,
27                    substrs=['next'])
28
29        self.expect("help", matching=True,
30                    substrs=['next'])
31
32    @no_debug_info_test
33    def test_help_on_help(self):
34        """Testing the help on the help facility."""
35        self.expect("help help", matching=True,
36                    substrs=['--hide-aliases',
37                             '--hide-user-commands'])
38
39    @no_debug_info_test
40    def test_help_arch(self):
41        """Test 'help arch' which should list of supported architectures."""
42        self.expect("help arch",
43                    substrs=['arm', 'i386', 'x86_64'])
44
45    @no_debug_info_test
46    def test_help_version(self):
47        """Test 'help version' and 'version' commands."""
48        self.expect("help version",
49                    substrs=['Show the LLDB debugger version.'])
50        self.expect("version",
51                    patterns=['lldb( version|-[0-9]+).*\n'])
52
53    @no_debug_info_test
54    def test_help_should_not_crash_lldb(self):
55        """Command 'help disasm' should not crash lldb."""
56        self.runCmd("help disasm", check=False)
57        self.runCmd("help unsigned-integer")
58
59    @no_debug_info_test
60    def test_help_memory_read_should_not_crash_lldb(self):
61        """Command 'help memory read' should not crash lldb."""
62        self.runCmd("help memory read", check=False)
63
64    @no_debug_info_test
65    def test_help_should_not_hang_emacsshell(self):
66        """Command 'settings set term-width 0' should not hang the help command."""
67        self.expect(
68            "settings set term-width 0",
69            COMMAND_FAILED_AS_EXPECTED,
70            error=True,
71            substrs=['error: 0 is out of range, valid values must be between'])
72        # self.runCmd("settings set term-width 0")
73        self.expect("help",
74                    startstr='Debugger commands:')
75
76    @no_debug_info_test
77    def test_help_breakpoint_set(self):
78        """Test that 'help breakpoint set' does not print out redundant lines of:
79        'breakpoint set [-s <shlib-name>] ...'."""
80        self.expect("help breakpoint set", matching=False,
81                    substrs=['breakpoint set [-s <shlib-name>]'])
82
83    @no_debug_info_test
84    def test_help_image_dump_symtab_should_not_crash(self):
85        """Command 'help image dump symtab' should not crash lldb."""
86        # 'image' is an alias for 'target modules'.
87        self.expect("help image dump symtab",
88                    substrs=['dump symtab',
89                             'sort-order'])
90
91    @no_debug_info_test
92    def test_help_image_du_sym_is_ambiguous(self):
93        """Command 'help image du sym' is ambiguous and spits out the list of candidates."""
94        self.expect("help image du sym",
95                    COMMAND_FAILED_AS_EXPECTED, error=True,
96                    substrs=['error: ambiguous command image du sym',
97                             'symfile',
98                             'symtab'])
99
100    @no_debug_info_test
101    def test_help_image_du_line_should_work(self):
102        """Command 'help image du line-table' is not ambiguous and should work."""
103        # 'image' is an alias for 'target modules'.
104        self.expect("help image du line", substrs=[
105                    'Dump the line table for one or more compilation units'])
106
107    @no_debug_info_test
108    def test_help_image_list_shows_positional_args(self):
109        """Command 'help image list' should describe positional args."""
110        # 'image' is an alias for 'target modules'.
111        self.expect("help image list", substrs=[
112                    '<shlib-name> [...]'])
113
114    @no_debug_info_test
115    def test_help_target_variable_syntax(self):
116        """Command 'help target variable' should display <variable-name> ..."""
117        self.expect("help target variable",
118                    substrs=['<variable-name> [<variable-name> [...]]'])
119
120    @no_debug_info_test
121    def test_help_watchpoint_and_its_args(self):
122        """Command 'help watchpoint', 'help watchpt-id', and 'help watchpt-id-list' should work."""
123        self.expect("help watchpoint",
124                    substrs=['delete', 'disable', 'enable', 'list'])
125        self.expect("help watchpt-id",
126                    substrs=['<watchpt-id>'])
127        self.expect("help watchpt-id-list",
128                    substrs=['<watchpt-id-list>'])
129
130    @no_debug_info_test
131    def test_help_watchpoint_set(self):
132        """Test that 'help watchpoint set' prints out 'expression' and 'variable'
133        as the possible subcommands."""
134        self.expect("help watchpoint set",
135                    substrs=['The following subcommands are supported:'],
136                    patterns=['expression +--',
137                              'variable +--'])
138
139    @no_debug_info_test
140    def test_help_po_hides_options(self):
141        """Test that 'help po' does not show all the options for expression"""
142        self.expect(
143            "help po",
144            substrs=[
145                '--show-all-children',
146                '--object-description'],
147            matching=False)
148
149    @no_debug_info_test
150    def test_help_run_hides_options(self):
151        """Test that 'help run' does not show all the options for process launch"""
152        self.expect("help run",
153                    substrs=['--arch', '--environment'], matching=False)
154
155    @no_debug_info_test
156    def test_help_next_shows_options(self):
157        """Test that 'help next' shows all the options for thread step-over"""
158        self.expect("help next",
159                    substrs=['--step-out-avoids-no-debug', '--run-mode'], matching=True)
160
161    @no_debug_info_test
162    def test_help_provides_alternatives(self):
163        """Test that help on commands that don't exist provides information on additional help avenues"""
164        self.expect(
165            "help thisisnotadebuggercommand",
166            substrs=[
167                "'thisisnotadebuggercommand' is not a known command.",
168                "Try 'help' to see a current list of commands.",
169                "Try 'apropos thisisnotadebuggercommand' for a list of related commands.",
170                "Try 'type lookup thisisnotadebuggercommand' for information on types, methods, functions, modules, etc."],
171            error=True)
172
173        self.expect(
174            "help process thisisnotadebuggercommand",
175            substrs=[
176                "'process thisisnotadebuggercommand' is not a known command.",
177                "Try 'help' to see a current list of commands.",
178                "Try 'apropos thisisnotadebuggercommand' for a list of related commands.",
179                "Try 'type lookup thisisnotadebuggercommand' for information on types, methods, functions, modules, etc."])
180
181    @no_debug_info_test
182    def test_custom_help_alias(self):
183        """Test that aliases pick up custom help text."""
184        def cleanup():
185            self.runCmd('command unalias afriendlyalias', check=False)
186            self.runCmd('command unalias averyfriendlyalias', check=False)
187
188        self.addTearDownHook(cleanup)
189        self.runCmd(
190            'command alias --help "I am a friendly alias" -- afriendlyalias help')
191        self.expect(
192            "help afriendlyalias",
193            matching=True,
194            substrs=['I am a friendly alias'])
195        self.runCmd(
196            'command alias --long-help "I am a very friendly alias" -- averyfriendlyalias help')
197        self.expect("help averyfriendlyalias", matching=True,
198                    substrs=['I am a very friendly alias'])
199    @no_debug_info_test
200    def test_alias_prints_origin(self):
201        """Test that 'help <unique_match_to_alias>' prints the alias origin."""
202        def cleanup():
203            self.runCmd('command unalias alongaliasname', check=False)
204
205        self.addTearDownHook(cleanup)
206        self.runCmd('command alias alongaliasname help')
207        self.expect("help alongaliasna", matching=True,
208                    substrs=["'alongaliasna' is an abbreviation for 'help'"])
209
210    @no_debug_info_test
211    def test_hidden_help(self):
212        self.expect("help -h",
213                    substrs=["_regexp-bt"])
214
215    @no_debug_info_test
216    def test_help_ambiguous(self):
217        self.expect("help g",
218                    substrs=["Help requested with ambiguous command name, possible completions:",
219                             "gdb-remote", "gui"])
220
221    @no_debug_info_test
222    def test_help_unknown_flag(self):
223        self.expect("help -z", error=True,
224                    substrs=["unknown or ambiguous option"])
225
226    @no_debug_info_test
227    def test_help_format_output(self):
228        """Test that help output reaches TerminalWidth."""
229        self.runCmd(
230            'settings set term-width 108')
231        self.expect(
232            "help format",
233            matching=True,
234            substrs=['<format> -- One of the format names'])
235
236    @no_debug_info_test
237    def test_help_option_group_format_options_usage(self):
238        """Test that help on commands that use OptionGroupFormat options provide relevant help specific to that command."""
239        self.expect(
240            "help memory read",
241            matching=True,
242            substrs=[
243                "-f <format> ( --format <format> )", "Specify a format to be used for display.",
244                "-s <byte-size> ( --size <byte-size> )", "The size in bytes to use when displaying with the selected format."])
245
246        self.expect(
247            "help memory write",
248            matching=True,
249            substrs=[
250                "-f <format> ( --format <format> )", "The format to use for each of the value to be written.",
251                "-s <byte-size> ( --size <byte-size> )", "The size in bytes to write from input file or each value."])
252
253    @no_debug_info_test
254    def test_help_shows_optional_short_options(self):
255        """Test that optional short options are printed and that they are in
256           alphabetical order with upper case options first."""
257        self.expect("help memory read",
258                    substrs=["memory read [-br]", "memory read [-AFLORTr]"])
259        self.expect("help target modules lookup",
260                    substrs=["target modules lookup [-Airv]"])
261
262    @no_debug_info_test
263    def test_help_shows_command_options_usage(self):
264        """Test that we start the usage section with a specific line."""
265        self.expect("help memory read", substrs=["Command Options Usage:\n  memory read"])
266
267    @no_debug_info_test
268    def test_help_detailed_information_spacing(self):
269        """Test that we put a break between the usage and the options help lines,
270           and between the options themselves."""
271        self.expect("help memory read", substrs=[
272                    "[<address-expression>]\n\n       -A ( --show-all-children )",
273                    # Starts with the end of the show-all-children line
274                    "to show.\n\n       -D"])
275
276    @no_debug_info_test
277    def test_help_detailed_information_ordering(self):
278        """Test that we order options alphabetically, upper case first."""
279        # You could test this with a simple regex like:
280        # <upper case>.*<later upper case>.*<lower case>.*<later lower case>
281        # Except that that could pass sometimes even with shuffled output.
282        # This makes sure that doesn't happen.
283
284        self.runCmd("help memory read")
285        got = self.res.GetOutput()
286        _, options_lines = got.split("Command Options Usage:")
287        options_lines = options_lines.lstrip().splitlines()
288
289        # Skip over "memory read [-xyz] lines.
290        while("memory read" in options_lines[0]):
291            options_lines.pop(0)
292        # Plus the newline after that.
293        options_lines.pop(0)
294
295        short_options = []
296        for line in options_lines:
297            # Ignore line breaks and descriptions.
298            # (not stripping the line here in case some line of the descriptions
299            # happens to start with "-")
300            if not line or not line.startswith("       -"):
301                continue
302            # This apears at the end after the options.
303            if "This command takes options and free form arguments." in line:
304                break
305            line = line.strip()
306            # The order of -- only options is not enforced so ignore their position.
307            if not line.startswith("--"):
308                # Save its short char name.
309                short_options.append(line[1])
310
311        self.assertEqual(sorted(short_options), short_options,
312                         "Short option help displayed in an incorrect order!")
313
314    @no_debug_info_test
315    def test_help_show_tags(self):
316        """ Check that memory find and memory read have the --show-tags option
317            but only memory read mentions binary output. """
318        self.expect("help memory read", patterns=[
319                    "--show-tags\n\s+Include memory tags in output "
320                    "\(does not apply to binary output\)."])
321        self.expect("help memory find", patterns=[
322                    "--show-tags\n\s+Include memory tags in output."])
323