debug 1.4.0 → 1.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a62295065b9bb4f9d498a21b32ea122ab680fd1e1b9794368ac2385858abf844
-  data.tar.gz: 0dc6f9aeb1ff23a47e0c399ee32ac80953821520cc52b0c4e27e30d7600a67bd
+  metadata.gz: c242bce58b031f61da73507f6b42a26f1ed8322679d1f0b3460d8fbc8c4b7a23
+  data.tar.gz: 543feb5e53a2c99ba04583edae4a13378667c97b13662f5a4d456dd6bacb17b5
 SHA512:
-  metadata.gz: 144d16fc2b8e377d7d25df0b09f088492647b76de2ffc1a841e09967caed2678f28fbaf24747fc351fd7e7d7c0d107cd39245ca0c8eff41547bce4f2ab35a8c3
-  data.tar.gz: 4e62e36b0fe72a2c1ce8e1dd44e6bae646e06b0d4d8d07072db595f908d00595252e35525a9ba1fde09a53f9a57781165c73e63d8eaa8a59a5e93219bd4c9ed5
+  metadata.gz: b5f6c58f38114e3179c3d5c062294ac276b53533fc4a6543114a883198318b672a8506990064f1b40d9f9597d3e1a933cb7c2363ea4cdd4ba0e0571279a80c73
+  data.tar.gz: 142a78dcdc449df6e0148857f992500aa88375707af067f36f1e3391fe2adb7ac8ff0f66623806c5488e94292167a369ca901084475e97b8dc38e32257ccbba0

data/CONTRIBUTING.md

@@ -14,15 +14,27 @@ If you spot any problem, please open an issue.
 ### Run all tests
 
 ```bash
-$ rake test
+$ rake test_all
+```
+
+### Run all console tests
+
+```bash
+$ rake test_console
+```
+
+### Run all protocol (DAP & CDP) tests
+
+```bash
+$ rake test_protocol
 ```
 
 ### Run specific test(s)
 
 
 ```bash
-$ ruby test/debug/bp_test.rb # run all tests in the specified file
-$ ruby test/debug/bp_test.rb -h # to see all the test options
+$ ruby test/console/break_test.rb # run all tests in the specified file
+$ ruby test/console/break_test.rb -h # to see all the test options
 ```
 
 ## Generate Tests
@@ -137,10 +149,10 @@ If the file already exists, **only method** will be added to it.
 ```ruby
 # frozen_string_literal: true
 
-require_relative '../support/test_case'
+require_relative '../support/console_test_case'
 
 module DEBUGGER__
-  class FooTest < TestCase
+  class FooTest < ConsoleTestCase
     def program
       <<~RUBY
         1| module Foo
@@ -154,7 +166,7 @@ module DEBUGGER__
         9| end
       RUBY
     end
-    
+
     def test_1629720194
       debug_code(program) do
         type 's'
@@ -249,6 +261,198 @@ Passes if `text` is not included in the last debugger log.
 
 Passes if `text` is included in the debuggee log.
 
+### Tests for DAP and CDP
+
+Currently, there are 2 kinds of test frameworks for DAP and CDP.
+
+1. Protocol-based tests
+
+If you want to write protocol-based tests, you should use the test generator.
+To run the test generator, you can enter `$ bin/gentest target.rb --open=vscode` in the terminal, VSCode will be executed.
+Also, if you enter `$ bin/gentest target.rb --open=chrome` there, Chrome will be executed.
+If you need to modify existing tests, it is basically a good idea to regenerate them by the test generator instead of rewriting them directly.
+Please refer to [the Microsoft "Debug Adapter Protocol" article](https://microsoft.github.io/debug-adapter-protocol/specification) to learn more about DAP formats.
+Please refer to [the "Chrome DevTools Protocol" official documentation](https://chromedevtools.github.io/devtools-protocol/) to learn more about CDP formats.
+
+2. High-level tests
+
+High-level tests are designed to test both DAP and CDP for a single method.
+You can write tests as follows:
+**NOTE:** Use `req_terminate_debuggee` to finish debugging. You can't use any methods such as `req_continue`, `req_next` and so on.
+
+```ruby
+require_relative '../support/test_case'
+module DEBUGGER__
+  class BreakTest < TestCase
+    # PROGRAM is the target script.
+    PROGRAM = <<~RUBY
+      1| module Foo
+      2|   class Bar
+      3|     def self.a
+      4|       "hello"
+      5|     end
+      6|   end
+      7|   Bar.a
+      8|   bar = Bar.new
+      9| end
+    RUBY
+
+    def test_break1
+      run_protocol_scenario PROGRAM do # Start debugging with DAP and CDP
+        req_add_breakpoint 5 # Set a breakpoint on line 5.
+        req_add_breakpoint 8 # Set a breakpoint on line 8.
+        req_continue # Resume the program.
+        assert_line_num 5 # Check if debugger stops at line 5.
+        req_continue # Resume the program.
+        assert_line_num 8 # Check if debugger stops at line 8.
+        req_terminate_debuggee # Terminate debugging.
+      end
+    end
+  end
+end
+```
+
+#### API
+
+- run_protocol_scenario program, dap: true, cdp: true, &scenario
+
+Execute debugging `program` with `&scenario`. If you want to test it only for DAP, you can write as follows:
+
+`run_protocol_scenario program, cdp: false ...`
+
+- attach_to_dap_server(terminate_debuggee:)
+
+Attach to the running DAP server through UNIX Domain Socket.
+
+- attach_to_cdp_server
+
+Attach to the running CDP server through TCP/IP.
+
+- req_dap_disconnect
+
+Disconnect from the currently connected DAP server.
+
+- req_cdp_disconnect
+
+Disconnect from the currently connected CDP server.
+
+- req_add_breakpoint(lineno, path: temp_file_path, cond: nil)
+
+Sends request to rdbg to add a breakpoint.
+
+- req_delete_breakpoint bpnum
+
+Sends request to rdbg to delete a breakpoint.
+
+- req_set_exception_breakpoints(breakpoints)
+
+Sends request to rdbg to set exception breakpoints. e.g.
+
+```rb
+req_set_exception_breakpoints([{ name: "RuntimeError", condition: "a == 1" }])
+```
+
+Please note that `setExceptionBreakpoints` resets all exception breakpoints in every request.
+
+So the following code will only set breakpoint for `Exception`.
+
+```rb
+req_set_exception_breakpoints([{ name: "RuntimeError" }])
+req_set_exception_breakpoints([{ name: "Exception" }])
+```
+
+This means you can also use
+
+```rb
+req_set_exception_breakpoints([])
+```
+
+to clear all exception breakpoints.
+
+- req_continue
+
+Sends request to rdbg to resume the program.
+
+- req_step
+
+Sends request to rdbg to step into next method.
+
+- req_next
+
+Sends request to rdbg to step over next method.
+
+- req_finish
+
+Sends request to rdbg to step out of current method.
+
+- req_step_back
+
+Sends request to rdbg to step back from current method.
+
+- req_terminate_debuggee
+
+Sends request to rdbg to terminate the debuggee.
+
+- assert_hover_result(expected, expression)
+
+Passes if result of `expression` matches `expected`.
+
+`expected` need to be a Hash object as follows:
+
+`assert_hover_result({value: '2', type: 'Integer'}, 'a')`
+
+NOTE: `value` and `type` need to be strings.
+
+- assert_repl_result(expected, expression)
+
+Passes if result of `expression` matches `expected`.
+
+`expected` need to be a Hash object as follows:
+
+`assert_repl_result({value: '2', type: 'Integer'}, 'a')`
+
+NOTE: `value` and `type` need to be strings.
+
+- assert_watch_result(expected, expression)
+
+Passes if result of `expression` matches `expected`.
+
+`expected` need to be a Hash object as follows:
+
+`assert_watch_result({value: '2', type: 'Integer'}, 'a')`
+
+NOTE: `value` and `type` need to be strings.
+
+- assert_line_num(expected)
+
+Passes if `expected` is equal to the location where debugger stops.
+
+- assert_locals_result(expected)
+
+Passes if all of `expected` local variable entries match the ones returned by debugger.
+
+An variable entry looks like this: `{ name: "bar", value: "nil", type: "NilClass" }`.
+
+Please note that both `value` and `type` need to be strings.
+
+- assert_threads_result(expected)
+
+Passes if both conditions are true:
+
+1. The number of expected patterns matches the number of threads.
+2. Every pattern matches a thread name. Notice that the order of threads info is not guaranteed.
+
+Example:
+
+```
+assert_threads_result(
+  [
+    /\.rb:\d:in `<main>'/,
+    /\.rb:\d:in `block in foo'/
+  ]
+)
+```
+
 ## To Update README
 
 This project generates `README.md` from the template `misc/README.md.erb`

data/Gemfile

@@ -6,3 +6,5 @@ gem "rake"
 gem "rake-compiler"
 gem "test-unit", "~> 3.0"
 gem "test-unit-rr"
+gem "json-schema"
+gem "test-unit-launchable"