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_should_not_hang_emacsshell(self):
61        """Command 'settings set term-width 0' should not hang the help command."""
62        self.expect(
63            "settings set term-width 0",
64            COMMAND_FAILED_AS_EXPECTED,
65            error=True,
66            substrs=['error: 0 is out of range, valid values must be between'])
67        # self.runCmd("settings set term-width 0")
68        self.expect("help",
69                    startstr='Debugger commands:')
70
71    @no_debug_info_test
72    def test_help_breakpoint_set(self):
73        """Test that 'help breakpoint set' does not print out redundant lines of:
74        'breakpoint set [-s <shlib-name>] ...'."""
75        self.expect("help breakpoint set", matching=False,
76                    substrs=['breakpoint set [-s <shlib-name>]'])
77
78    @no_debug_info_test
79    def test_help_image_dump_symtab_should_not_crash(self):
80        """Command 'help image dump symtab' should not crash lldb."""
81        # 'image' is an alias for 'target modules'.
82        self.expect("help image dump symtab",
83                    substrs=['dump symtab',
84                             'sort-order'])
85
86    @no_debug_info_test
87    def test_help_image_du_sym_is_ambiguous(self):
88        """Command 'help image du sym' is ambiguous and spits out the list of candidates."""
89        self.expect("help image du sym",
90                    COMMAND_FAILED_AS_EXPECTED, error=True,
91                    substrs=['error: ambiguous command image du sym',
92                             'symfile',
93                             'symtab'])
94
95    @no_debug_info_test
96    def test_help_image_du_line_should_work(self):
97        """Command 'help image du line-table' is not ambiguous and should work."""
98        # 'image' is an alias for 'target modules'.
99        self.expect("help image du line", substrs=[
100                    'Dump the line table for one or more compilation units'])
101
102    @no_debug_info_test
103    def test_help_target_variable_syntax(self):
104        """Command 'help target variable' should display <variable-name> ..."""
105        self.expect("help target variable",
106                    substrs=['<variable-name> [<variable-name> [...]]'])
107
108    @no_debug_info_test
109    def test_help_watchpoint_and_its_args(self):
110        """Command 'help watchpoint', 'help watchpt-id', and 'help watchpt-id-list' should work."""
111        self.expect("help watchpoint",
112                    substrs=['delete', 'disable', 'enable', 'list'])
113        self.expect("help watchpt-id",
114                    substrs=['<watchpt-id>'])
115        self.expect("help watchpt-id-list",
116                    substrs=['<watchpt-id-list>'])
117
118    @no_debug_info_test
119    def test_help_watchpoint_set(self):
120        """Test that 'help watchpoint set' prints out 'expression' and 'variable'
121        as the possible subcommands."""
122        self.expect("help watchpoint set",
123                    substrs=['The following subcommands are supported:'],
124                    patterns=['expression +--',
125                              'variable +--'])
126
127    @no_debug_info_test
128    def test_help_po_hides_options(self):
129        """Test that 'help po' does not show all the options for expression"""
130        self.expect(
131            "help po",
132            substrs=[
133                '--show-all-children',
134                '--object-description'],
135            matching=False)
136
137    @no_debug_info_test
138    def test_help_run_hides_options(self):
139        """Test that 'help run' does not show all the options for process launch"""
140        self.expect("help run",
141                    substrs=['--arch', '--environment'], matching=False)
142
143    @no_debug_info_test
144    def test_help_next_shows_options(self):
145        """Test that 'help next' shows all the options for thread step-over"""
146        self.expect("help next",
147                    substrs=['--step-out-avoids-no-debug', '--run-mode'], matching=True)
148
149    @no_debug_info_test
150    def test_help_provides_alternatives(self):
151        """Test that help on commands that don't exist provides information on additional help avenues"""
152        self.expect(
153            "help thisisnotadebuggercommand",
154            substrs=[
155                "'thisisnotadebuggercommand' is not a known command.",
156                "Try 'help' to see a current list of commands.",
157                "Try 'apropos thisisnotadebuggercommand' for a list of related commands.",
158                "Try 'type lookup thisisnotadebuggercommand' for information on types, methods, functions, modules, etc."],
159            error=True)
160
161        self.expect(
162            "help process thisisnotadebuggercommand",
163            substrs=[
164                "'process thisisnotadebuggercommand' is not a known command.",
165                "Try 'help' to see a current list of commands.",
166                "Try 'apropos thisisnotadebuggercommand' for a list of related commands.",
167                "Try 'type lookup thisisnotadebuggercommand' for information on types, methods, functions, modules, etc."])
168
169    @no_debug_info_test
170    def test_custom_help_alias(self):
171        """Test that aliases pick up custom help text."""
172        def cleanup():
173            self.runCmd('command unalias afriendlyalias', check=False)
174            self.runCmd('command unalias averyfriendlyalias', check=False)
175
176        self.addTearDownHook(cleanup)
177        self.runCmd(
178            'command alias --help "I am a friendly alias" -- afriendlyalias help')
179        self.expect(
180            "help afriendlyalias",
181            matching=True,
182            substrs=['I am a friendly alias'])
183        self.runCmd(
184            'command alias --long-help "I am a very friendly alias" -- averyfriendlyalias help')
185        self.expect("help averyfriendlyalias", matching=True,
186                    substrs=['I am a very friendly alias'])
187    @no_debug_info_test
188    def test_alias_prints_origin(self):
189        """Test that 'help <unique_match_to_alias>' prints the alias origin."""
190        def cleanup():
191            self.runCmd('command unalias alongaliasname', check=False)
192
193        self.addTearDownHook(cleanup)
194        self.runCmd('command alias alongaliasname help')
195        self.expect("help alongaliasna", matching=True,
196                    substrs=["'alongaliasna' is an abbreviation for 'help'"])
197
198    @no_debug_info_test
199    def test_hidden_help(self):
200        self.expect("help -h",
201                    substrs=["_regexp-bt"])
202
203    @no_debug_info_test
204    def test_help_ambiguous(self):
205        self.expect("help g",
206                    substrs=["Help requested with ambiguous command name, possible completions:",
207                             "gdb-remote", "gui"])
208
209    @no_debug_info_test
210    def test_help_unknown_flag(self):
211        self.expect("help -z", error=True,
212                    substrs=["unknown or ambiguous option"])
213
214    @no_debug_info_test
215    def test_help_format_output(self):
216        """Test that help output reaches TerminalWidth."""
217        self.runCmd(
218            'settings set term-width 108')
219        self.expect(
220            "help format",
221            matching=True,
222            substrs=['<format> -- One of the format names'])
223