lldb/packages/Python/lldbsuite/test/tools/lldb-dap/lldbdap_testcase.py

   1 import os
   2 import time
   3
   4 import dap_server
   5 from lldbsuite.test.lldbtest import *
   6 from lldbsuite.test import lldbplatformutil
   7 import lldbgdbserverutils
   8
   9
  10 class DAPTestCaseBase(TestBase):
  11     # set timeout based on whether ASAN was enabled or not. Increase
  12     # timeout by a factor of 10 if ASAN is enabled.
  13     timeoutval = 10 * (10 if ('ASAN_OPTIONS' in os.environ) else 1)
  14     NO_DEBUG_INFO_TESTCASE = True
  15
  16     def create_debug_adaptor(self, lldbDAPEnv=None):
  17         """Create the Visual Studio Code debug adaptor"""
  18         self.assertTrue(
  19             is_exe(self.lldbDAPExec), "lldb-dap must exist and be executable"
  20         )
  21         log_file_path = self.getBuildArtifact("dap.txt")
  22         self.dap_server = dap_server.DebugAdaptorServer(
  23             executable=self.lldbDAPExec,
  24             init_commands=self.setUpCommands(),
  25             log_file=log_file_path,
  26             env=lldbDAPEnv,
  27         )
  28
  29     def build_and_create_debug_adaptor(self, lldbDAPEnv=None):
  30         self.build()
  31         self.create_debug_adaptor(lldbDAPEnv)
  32
  33     def set_source_breakpoints(self, source_path, lines, data=None):
  34         """Sets source breakpoints and returns an array of strings containing
  35         the breakpoint IDs ("1", "2") for each breakpoint that was set.
  36         Parameter data is array of data objects for breakpoints.
  37         Each object in data is 1:1 mapping with the entry in lines.
  38         It contains optional location/hitCondition/logMessage parameters.
  39         """
  40         response = self.dap_server.request_setBreakpoints(source_path, lines, data)
  41         if response is None:
  42             return []
  43         breakpoints = response["body"]["breakpoints"]
  44         breakpoint_ids = []
  45         for breakpoint in breakpoints:
  46             breakpoint_ids.append("%i" % (breakpoint["id"]))
  47         return breakpoint_ids
  48
  49     def set_function_breakpoints(self, functions, condition=None, hitCondition=None):
  50         """Sets breakpoints by function name given an array of function names
  51         and returns an array of strings containing the breakpoint IDs
  52         ("1", "2") for each breakpoint that was set.
  53         """
  54         response = self.dap_server.request_setFunctionBreakpoints(
  55             functions, condition=condition, hitCondition=hitCondition
  56         )
  57         if response is None:
  58             return []
  59         breakpoints = response["body"]["breakpoints"]
  60         breakpoint_ids = []
  61         for breakpoint in breakpoints:
  62             breakpoint_ids.append("%i" % (breakpoint["id"]))
  63         return breakpoint_ids
  64
  65     def waitUntil(self, condition_callback):
  66         for _ in range(20):
  67             if condition_callback():
  68                 return True
  69             time.sleep(0.5)
  70         return False
  71
  72     def verify_breakpoint_hit(self, breakpoint_ids):
  73         """Wait for the process we are debugging to stop, and verify we hit
  74         any breakpoint location in the "breakpoint_ids" array.
  75         "breakpoint_ids" should be a list of breakpoint ID strings
  76         (["1", "2"]). The return value from self.set_source_breakpoints()
  77         or self.set_function_breakpoints() can be passed to this function"""
  78         stopped_events = self.dap_server.wait_for_stopped()
  79         for stopped_event in stopped_events:
  80             if "body" in stopped_event:
  81                 body = stopped_event["body"]
  82                 if "reason" not in body:
  83                     continue
  84                 if (
  85                     body["reason"] != "breakpoint"
  86                     and body["reason"] != "instruction breakpoint"
  87                 ):
  88                     continue
  89                 if "description" not in body:
  90                     continue
  91                 # Descriptions for breakpoints will be in the form
  92                 # "breakpoint 1.1", so look for any description that matches
  93                 # ("breakpoint 1.") in the description field as verification
  94                 # that one of the breakpoint locations was hit. DAP doesn't
  95                 # allow breakpoints to have multiple locations, but LLDB does.
  96                 # So when looking at the description we just want to make sure
  97                 # the right breakpoint matches and not worry about the actual
  98                 # location.
  99                 description = body["description"]
 100                 for breakpoint_id in breakpoint_ids:
 101                     match_desc = "breakpoint %s." % (breakpoint_id)
 102                     if match_desc in description:
 103                         return
 104         self.assertTrue(False, "breakpoint not hit")
 105
 106     def verify_stop_exception_info(self, expected_description, timeout=timeoutval):
 107         """Wait for the process we are debugging to stop, and verify the stop
 108         reason is 'exception' and that the description matches
 109         'expected_description'
 110         """
 111         stopped_events = self.dap_server.wait_for_stopped(timeout=timeout)
 112         for stopped_event in stopped_events:
 113             print("stopped_event", stopped_event)
 114             if "body" in stopped_event:
 115                 body = stopped_event["body"]
 116                 if "reason" not in body:
 117                     continue
 118                 if body["reason"] != "exception":
 119                     continue
 120                 if "description" not in body:
 121                     continue
 122                 description = body["description"]
 123                 if expected_description == description:
 124                     return True
 125         return False
 126
 127     def verify_commands(self, flavor, output, commands):
 128         self.assertTrue(output and len(output) > 0, "expect console output")
 129         lines = output.splitlines()
 130         prefix = "(lldb) "
 131         for cmd in commands:
 132             found = False
 133             for line in lines:
 134                 if len(cmd) > 0 and (cmd[0] == "!" or cmd[0] == "?"):
 135                     cmd = cmd[1:]
 136                 if line.startswith(prefix) and cmd in line:
 137                     found = True
 138                     break
 139             self.assertTrue(
 140                 found, "verify '%s' found in console output for '%s'" % (cmd, flavor)
 141             )
 142
 143     def get_dict_value(self, d, key_path):
 144         """Verify each key in the key_path array is in contained in each
 145         dictionary within "d". Assert if any key isn't in the
 146         corresponding dictionary. This is handy for grabbing values from VS
 147         Code response dictionary like getting
 148         response['body']['stackFrames']
 149         """
 150         value = d
 151         for key in key_path:
 152             if key in value:
 153                 value = value[key]
 154             else:
 155                 self.assertTrue(
 156                     key in value,
 157                     'key "%s" from key_path "%s" not in "%s"' % (key, key_path, d),
 158                 )
 159         return value
 160
 161     def get_stackFrames_and_totalFramesCount(
 162         self, threadId=None, startFrame=None, levels=None, dump=False
 163     ):
 164         response = self.dap_server.request_stackTrace(
 165             threadId=threadId, startFrame=startFrame, levels=levels, dump=dump
 166         )
 167         if response:
 168             stackFrames = self.get_dict_value(response, ["body", "stackFrames"])
 169             totalFrames = self.get_dict_value(response, ["body", "totalFrames"])
 170             self.assertTrue(
 171                 totalFrames > 0,
 172                 "verify totalFrames count is provided by extension that supports "
 173                 "async frames loading",
 174             )
 175             return (stackFrames, totalFrames)
 176         return (None, 0)
 177
 178     def get_stackFrames(self, threadId=None, startFrame=None, levels=None, dump=False):
 179         (stackFrames, totalFrames) = self.get_stackFrames_and_totalFramesCount(
 180             threadId=threadId, startFrame=startFrame, levels=levels, dump=dump
 181         )
 182         return stackFrames
 183
 184     def get_exceptionInfo(self, threadId=None):
 185         response = self.dap_server.request_exceptionInfo(threadId=threadId)
 186         return self.get_dict_value(response, ["body"])
 187
 188     def get_source_and_line(self, threadId=None, frameIndex=0):
 189         stackFrames = self.get_stackFrames(
 190             threadId=threadId, startFrame=frameIndex, levels=1
 191         )
 192         if stackFrames is not None:
 193             stackFrame = stackFrames[0]
 194             ["source", "path"]
 195             if "source" in stackFrame:
 196                 source = stackFrame["source"]
 197                 if "path" in source:
 198                     if "line" in stackFrame:
 199                         return (source["path"], stackFrame["line"])
 200         return ("", 0)
 201
 202     def get_stdout(self, timeout=0.0):
 203         return self.dap_server.get_output("stdout", timeout=timeout)
 204
 205     def get_console(self, timeout=0.0):
 206         return self.dap_server.get_output("console", timeout=timeout)
 207
 208     def collect_console(self, timeout_secs, pattern=None):
 209         return self.dap_server.collect_output(
 210             "console", timeout_secs=timeout_secs, pattern=pattern
 211         )
 212
 213     def collect_stdout(self, timeout_secs, pattern=None):
 214         return self.dap_server.collect_output(
 215             "stdout", timeout_secs=timeout_secs, pattern=pattern
 216         )
 217
 218     def get_local_as_int(self, name, threadId=None):
 219         value = self.dap_server.get_local_variable_value(name, threadId=threadId)
 220         # 'value' may have the variable value and summary.
 221         # Extract the variable value since summary can have nonnumeric characters.
 222         value = value.split(" ")[0]
 223         if value.startswith("0x"):
 224             return int(value, 16)
 225         elif value.startswith("0"):
 226             return int(value, 8)
 227         else:
 228             return int(value)
 229
 230     def set_local(self, name, value, id=None):
 231         """Set a top level local variable only."""
 232         return self.dap_server.request_setVariable(1, name, str(value), id=id)
 233
 234     def set_global(self, name, value, id=None):
 235         """Set a top level global variable only."""
 236         return self.dap_server.request_setVariable(2, name, str(value), id=id)
 237
 238     def stepIn(
 239         self, threadId=None, targetId=None, waitForStop=True, granularity="statement"
 240     ):
 241         self.dap_server.request_stepIn(
 242             threadId=threadId, targetId=targetId, granularity=granularity
 243         )
 244         if waitForStop:
 245             return self.dap_server.wait_for_stopped()
 246         return None
 247
 248     def stepOver(self, threadId=None, waitForStop=True, granularity="statement"):
 249         self.dap_server.request_next(threadId=threadId, granularity=granularity)
 250         if waitForStop:
 251             return self.dap_server.wait_for_stopped()
 252         return None
 253
 254     def stepOut(self, threadId=None, waitForStop=True):
 255         self.dap_server.request_stepOut(threadId=threadId)
 256         if waitForStop:
 257             return self.dap_server.wait_for_stopped()
 258         return None
 259
 260     def continue_to_next_stop(self):
 261         self.dap_server.request_continue()
 262         return self.dap_server.wait_for_stopped()
 263
 264     def continue_to_breakpoints(self, breakpoint_ids):
 265         self.dap_server.request_continue()
 266         self.verify_breakpoint_hit(breakpoint_ids)
 267
 268     def continue_to_exception_breakpoint(self, filter_label):
 269         self.dap_server.request_continue()
 270         self.assertTrue(
 271             self.verify_stop_exception_info(filter_label),
 272             'verify we got "%s"' % (filter_label),
 273         )
 274
 275     def continue_to_exit(self, exitCode=0):
 276         self.dap_server.request_continue()
 277         stopped_events = self.dap_server.wait_for_stopped()
 278         self.assertEqual(
 279             len(stopped_events), 1, "stopped_events = {}".format(stopped_events)
 280         )
 281         self.assertEqual(
 282             stopped_events[0]["event"], "exited", "make sure program ran to completion"
 283         )
 284         self.assertEqual(
 285             stopped_events[0]["body"]["exitCode"],
 286             exitCode,
 287             "exitCode == %i" % (exitCode),
 288         )
 289
 290     def disassemble(self, threadId=None, frameIndex=None):
 291         stackFrames = self.get_stackFrames(
 292             threadId=threadId, startFrame=frameIndex, levels=1
 293         )
 294         self.assertIsNotNone(stackFrames)
 295         memoryReference = stackFrames[0]["instructionPointerReference"]
 296         self.assertIsNotNone(memoryReference)
 297
 298         if memoryReference not in self.dap_server.disassembled_instructions:
 299             self.dap_server.request_disassemble(memoryReference=memoryReference)
 300
 301         return self.dap_server.disassembled_instructions[memoryReference]
 302
 303     def attach(
 304         self,
 305         program=None,
 306         pid=None,
 307         waitFor=None,
 308         trace=None,
 309         initCommands=None,
 310         preRunCommands=None,
 311         stopCommands=None,
 312         exitCommands=None,
 313         attachCommands=None,
 314         coreFile=None,
 315         disconnectAutomatically=True,
 316         terminateCommands=None,
 317         postRunCommands=None,
 318         sourceMap=None,
 319         sourceInitFile=False,
 320         expectFailure=False,
 321         gdbRemotePort=None,
 322         gdbRemoteHostname=None,
 323     ):
 324         """Build the default Makefile target, create the DAP debug adaptor,
 325         and attach to the process.
 326         """
 327
 328         # Make sure we disconnect and terminate the DAP debug adaptor even
 329         # if we throw an exception during the test case.
 330         def cleanup():
 331             if disconnectAutomatically:
 332                 self.dap_server.request_disconnect(terminateDebuggee=True)
 333             self.dap_server.terminate()
 334
 335         # Execute the cleanup function during test case tear down.
 336         self.addTearDownHook(cleanup)
 337         # Initialize and launch the program
 338         self.dap_server.request_initialize(sourceInitFile)
 339         response = self.dap_server.request_attach(
 340             program=program,
 341             pid=pid,
 342             waitFor=waitFor,
 343             trace=trace,
 344             initCommands=initCommands,
 345             preRunCommands=preRunCommands,
 346             stopCommands=stopCommands,
 347             exitCommands=exitCommands,
 348             attachCommands=attachCommands,
 349             terminateCommands=terminateCommands,
 350             coreFile=coreFile,
 351             postRunCommands=postRunCommands,
 352             sourceMap=sourceMap,
 353             gdbRemotePort=gdbRemotePort,
 354             gdbRemoteHostname=gdbRemoteHostname,
 355         )
 356         if expectFailure:
 357             return response
 358         if not (response and response["success"]):
 359             self.assertTrue(
 360                 response["success"], "attach failed (%s)" % (response["message"])
 361             )
 362
 363     def launch(
 364         self,
 365         program=None,
 366         args=None,
 367         cwd=None,
 368         env=None,
 369         stopOnEntry=False,
 370         disableASLR=False,
 371         disableSTDIO=False,
 372         shellExpandArguments=False,
 373         trace=False,
 374         initCommands=None,
 375         preRunCommands=None,
 376         stopCommands=None,
 377         exitCommands=None,
 378         terminateCommands=None,
 379         sourcePath=None,
 380         debuggerRoot=None,
 381         sourceInitFile=False,
 382         launchCommands=None,
 383         sourceMap=None,
 384         disconnectAutomatically=True,
 385         runInTerminal=False,
 386         expectFailure=False,
 387         postRunCommands=None,
 388         enableAutoVariableSummaries=False,
 389         displayExtendedBacktrace=False,
 390         enableSyntheticChildDebugging=False,
 391         commandEscapePrefix=None,
 392         customFrameFormat=None,
 393         customThreadFormat=None,
 394     ):
 395         """Sending launch request to dap"""
 396
 397         # Make sure we disconnect and terminate the DAP debug adapter,
 398         # if we throw an exception during the test case
 399         def cleanup():
 400             if disconnectAutomatically:
 401                 self.dap_server.request_disconnect(terminateDebuggee=True)
 402             self.dap_server.terminate()
 403
 404         # Execute the cleanup function during test case tear down.
 405         self.addTearDownHook(cleanup)
 406
 407         # Initialize and launch the program
 408         self.dap_server.request_initialize(sourceInitFile)
 409         response = self.dap_server.request_launch(
 410             program,
 411             args=args,
 412             cwd=cwd,
 413             env=env,
 414             stopOnEntry=stopOnEntry,
 415             disableASLR=disableASLR,
 416             disableSTDIO=disableSTDIO,
 417             shellExpandArguments=shellExpandArguments,
 418             trace=trace,
 419             initCommands=initCommands,
 420             preRunCommands=preRunCommands,
 421             stopCommands=stopCommands,
 422             exitCommands=exitCommands,
 423             terminateCommands=terminateCommands,
 424             sourcePath=sourcePath,
 425             debuggerRoot=debuggerRoot,
 426             launchCommands=launchCommands,
 427             sourceMap=sourceMap,
 428             runInTerminal=runInTerminal,
 429             postRunCommands=postRunCommands,
 430             enableAutoVariableSummaries=enableAutoVariableSummaries,
 431             displayExtendedBacktrace=displayExtendedBacktrace,
 432             enableSyntheticChildDebugging=enableSyntheticChildDebugging,
 433             commandEscapePrefix=commandEscapePrefix,
 434             customFrameFormat=customFrameFormat,
 435             customThreadFormat=customThreadFormat,
 436         )
 437
 438         if expectFailure:
 439             return response
 440
 441         if not (response and response["success"]):
 442             self.assertTrue(
 443                 response["success"], "launch failed (%s)" % (response["message"])
 444             )
 445         return response
 446
 447     def build_and_launch(
 448         self,
 449         program,
 450         args=None,
 451         cwd=None,
 452         env=None,
 453         stopOnEntry=False,
 454         disableASLR=False,
 455         disableSTDIO=False,
 456         shellExpandArguments=False,
 457         trace=False,
 458         initCommands=None,
 459         preRunCommands=None,
 460         stopCommands=None,
 461         exitCommands=None,
 462         terminateCommands=None,
 463         sourcePath=None,
 464         debuggerRoot=None,
 465         sourceInitFile=False,
 466         runInTerminal=False,
 467         disconnectAutomatically=True,
 468         postRunCommands=None,
 469         lldbDAPEnv=None,
 470         enableAutoVariableSummaries=False,
 471         displayExtendedBacktrace=False,
 472         enableSyntheticChildDebugging=False,
 473         commandEscapePrefix=None,
 474         customFrameFormat=None,
 475         customThreadFormat=None,
 476         launchCommands=None,
 477         expectFailure=False,
 478     ):
 479         """Build the default Makefile target, create the DAP debug adaptor,
 480         and launch the process.
 481         """
 482         self.build_and_create_debug_adaptor(lldbDAPEnv)
 483         self.assertTrue(os.path.exists(program), "executable must exist")
 484
 485         return self.launch(
 486             program,
 487             args,
 488             cwd,
 489             env,
 490             stopOnEntry,
 491             disableASLR,
 492             disableSTDIO,
 493             shellExpandArguments,
 494             trace,
 495             initCommands,
 496             preRunCommands,
 497             stopCommands,
 498             exitCommands,
 499             terminateCommands,
 500             sourcePath,
 501             debuggerRoot,
 502             sourceInitFile,
 503             runInTerminal=runInTerminal,
 504             disconnectAutomatically=disconnectAutomatically,
 505             postRunCommands=postRunCommands,
 506             enableAutoVariableSummaries=enableAutoVariableSummaries,
 507             enableSyntheticChildDebugging=enableSyntheticChildDebugging,
 508             displayExtendedBacktrace=displayExtendedBacktrace,
 509             commandEscapePrefix=commandEscapePrefix,
 510             customFrameFormat=customFrameFormat,
 511             customThreadFormat=customThreadFormat,
 512             launchCommands=launchCommands,
 513             expectFailure=expectFailure,
 514         )
 515
 516     def getBuiltinDebugServerTool(self):
 517         # Tries to find simulation/lldb-server/gdbserver tool path.
 518         server_tool = None
 519         if lldbplatformutil.getPlatform() == "linux":
 520             server_tool = lldbgdbserverutils.get_lldb_server_exe()
 521             if server_tool is None:
 522                 self.dap_server.request_disconnect(terminateDebuggee=True)
 523                 self.assertIsNotNone(server_tool, "lldb-server not found.")
 524         elif lldbplatformutil.getPlatform() == "macosx":
 525             server_tool = lldbgdbserverutils.get_debugserver_exe()
 526             if server_tool is None:
 527                 self.dap_server.request_disconnect(terminateDebuggee=True)
 528                 self.assertIsNotNone(server_tool, "debugserver not found.")
 529         return server_tool