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