debug 1.3.4 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58d7a886dc29b717d9f31ca7859a40a881a251a4c5e64705ac38de1cb94c0f32
-  data.tar.gz: a58994d8d302dac0aedd63775b8d81769d326a6bb0746d9953182fa8b36894fd
+  metadata.gz: cb9c418ee481ed3b473973d522bb811949f6123501709d3385d9b2bf2a46d993
+  data.tar.gz: d0036bac1930ec7e920e9faeb66556a4a9132342ed604a909e15f9d02b4d6963
 SHA512:
-  metadata.gz: 3988bc3fd10cab3592a9f6b3b816dd2f5cabf5e8e4bceaec646011a1663b037a7f9683008c77d1c91a0a8f984540c16ef5975fa14b93f84b6cca5915e98df440
-  data.tar.gz: 4283c41adf172ae2d1e51bb34adfb65ab2b521862bae6be7bd08ba485bea178e0e2ec511db7b9f0297e2aea4e4d2ac249887bb9271f51d71d6beb76a0aee63d0
+  metadata.gz: e9cb09ddeee150eac35f5f3044106f482e54e16b41cee4ab6d0678fa92a2c1aefad350412bdc00997892733cf0a58312372d3f40c0f22d5262223de46f31cd9b
+  data.tar.gz: 68a846cc25aca6aab1429b3b36da57977c7c5671b21e9c6381f6d0b6d5fe7d28979fac53d1958da4de00c10445722a3fe1e386a871ee8b5638b3bf541cbf19ad

data/CONTRIBUTING.md

@@ -14,23 +14,41 @@ 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
+
 There is a test generator in `debug.rb` project to make it easier to write tests.
+
 ### Quickstart
-This section shows you how to create test file by test generator. For more advanced informations on creating tests, please take a look at [gentest options](#gentest-options). (You can also check by `$bin/gentest -h`)
+
+This section shows you how to create test file by test generator. For more advanced information on creating tests, please take a look at [gentest options](#gentest-options). (You can also check by `$bin/gentest -h`)
+
 #### 1. Create a target file for debuggee.
+
 Let's say, we created `target.rb` which is located in top level directory of debugger.
+
 ```ruby
 module Foo
   class Bar
@@ -42,11 +60,15 @@ module Foo
   bar = Bar.new
 end
 ```
+
 #### 2. Run `gentest` as shown in the example below.
+
 ```shell
 $ bin/gentest target.rb
 ```
+
 #### 3. Debugger will be executed. You can type any debug commands.
+
 ```shell
 $ bin/gentest target.rb
 DEBUGGER: Session start (pid: 11139)
@@ -119,8 +141,11 @@ created: /Users/naotto/workspace/debug/test/tool/../debug/foo_test.rb
     class: FooTest
     method: test_1629720194
 ```
+
 #### 4. The test file will be created as `test/debug/foo_test.rb`.
+
 If the file already exists, **only method** will be added to it.
+
 ```ruby
 # frozen_string_literal: true
 
@@ -204,17 +229,217 @@ end
 ```
 
 #### gentest options
+
 You can get more information about `gentest` here.
 
-The default method name is `test_#{some integer numbers}`, the class name is `FooTest`, and the file name will be `foo_test.rb`.
+The default method name is `test_#{some integer numbers}`, the class name is `FooTest#{some integer numbers}`, and the file name will be `foo_test.rb`.
 The following table shows examples of the gentest options.
 
 | Command | Description | File | Class | Method |
 | --- | --- | --- | --- | --- |
-| `$ bin/gentest target.rb` | Run without any options | `foo_test.rb` | `FooTest` | `test_#{some integer numbers}` |
-| `$ bin/gentest target.rb -c step` | Specify the class name | `step_test.rb` | `StepTest` | `test_#{some integer numbers}` |
-| `$ bin/gentest target.rb -m test_step` | Specify the method name | `foo_test.rb` | `FooTest` | `test_step` |
-| `$ bin/gentest target.rb -c step -m test_step` | Specify the class name and the method name | `step_test.rb` | `StepTest` | `test_step` |
+| `$ bin/gentest target.rb` | Run without any options | `foo_test.rb` | `FooTest...` | `test_...` |
+| `$ bin/gentest target.rb --open=vscode` | Run the debugger with VScode | `foo_test.rb` | `FooTest...` | `test_...` |
+| `$ bin/gentest target.rb -c step` | Specify the class name | `step_test.rb` | `StepTest...` | `test_...` |
+| `$ bin/gentest target.rb -m test_step` | Specify the method name | `foo_test.rb` | `FooTest...` | `test_step` |
+| `$ bin/gentest target.rb -c step -m test_step` | Specify the class name and the method name | `step_test.rb` | `StepTest...` | `test_step` |
+
+### Assertions
+
+- assert_line_num(expected)
+
+Passes if `expected` is equal to the location where debugger stops.
+
+- assert_line_text(text)
+
+Passes if `text` is included in the last debugger log.
+
+- assert_no_line_text(text)
+
+Passes if `text` is not included in the last debugger log.
+
+- assert_debuggee_line_text(text)
+
+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 [Procol viewer for "Chrome DevTools Protocol"](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 ...`
+
+- 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_reattach
+
+Passes if reattaching to rdbg is successful.
+
+- 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
 

data/Gemfile

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

data/README.md

@@ -1,19 +1,23 @@
-[![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster)
+[![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster) [![Protocol](https://github.com/ruby/debug/actions/workflows/protocol.yml/badge.svg)](https://github.com/ruby/debug/actions/workflows/protocol.yml)
 
 # debug.rb
 
-This library provides debugging functionality to Ruby.
+This library provides debugging functionality to Ruby (MRI) 2.6 and later.
 
 This debug.rb is replacement of traditional lib/debug.rb standard library which is implemented by `set_trace_func`.
 New debug.rb has several advantages:
 
 * Fast: No performance penalty on non-stepping mode and non-breakpoints.
 * [Remote debugging](#remote-debugging): Support remote debugging natively.
-  * UNIX domain socket
+  * UNIX domain socket (UDS)
   * TCP/IP
-  * Integration with rich debugger frontend
-    * VSCode/DAP ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg))
-    * Chrome DevTools
+  * Integration with rich debugger frontends
+
+     Frontend |  [Console](https://github.com/ruby/debug#invoke-as-a-remote-debuggee) | [VSCode](https://github.com/ruby/debug#vscode-integration) | [Chrome DevTool](#chrome-devtool-integration) |
+     ---|---|---|---|
+     Connection | UDS, TCP/IP | UDS, TCP/IP | TCP/IP |
+     Requirement | No | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome |
+
 * Extensible: application can introduce debugging support with several ways:
   * By `rdbg` command
   * By loading libraries with `-r` command line option
@@ -38,6 +42,9 @@ If you use Bundler, write the following line to your Gemfile.
 gem "debug", ">= 1.0.0"
 ```
 
+(The version constraint is important; `debug < 1.0.0` is an older,
+abandoned gem that is completely different from this product.)
+
 # HOW TO USE
 
 To use a debugger, roughly you will do the following steps:
@@ -60,8 +67,14 @@ There are several options for (1) and (2). Please choose your favorite way.
 
 ### Modify source code with [`binding.break`](#bindingbreak-method) (similar to `binding.pry` or `binding.irb`)
 
-If you can modify the source code, you can use the debugger by adding `require 'debug'` line at the top of your program and putting [`binding.break`](#bindingbreak-method) method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
-After that, you run the program as usual and you will enter the debug console at breakpoints you inserted.
+If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
+
+You can also use its 2 aliases in the same way:
+
+- `binding.b`
+- `debugger`
+
+After that, run the program as usual and you will enter the debug console at breakpoints you inserted.
 
 The following example shows the demonstration of [`binding.break`](#bindingbreak-method).
 
@@ -107,7 +120,7 @@ d => nil
       5| binding.break
       6| c = 3
       7| d = 4
-=>    8| binding.break                 # Again the program stops at here
+=>    8| binding.break                 # Again the program stops here
       9| p [a, b, c, d]
      10|
      11| __END__
@@ -128,7 +141,7 @@ d => 4
 ### Invoke the program from the debugger as a traditional debuggers
 
 If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
-Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger.
+Using `rdbg` command (or `bundle exec rdbg`) to launch the program without any modifications, you can run the program with the debugger.
 
 ```shell
 $ cat target.rb                        # Sample program
@@ -274,7 +287,12 @@ You can run your application as a remote debuggee and the remote debugger consol
 
 ### Invoke as a remote debuggee
 
-There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
+There are multiple ways to run your program as a debuggee:
+
+Stop at program start | [`rdbg` option](https://github.com/ruby/debug#rdbg---open-or-rdbg--o-for-short) | [require](https://github.com/ruby/debug#require-debugopen-in-a-program) | [debugger API](https://github.com/ruby/debug#start-by-method)
+---|---|---|---|
+Yes | `rdbg --open` | `require "debug/open"` | `DEBUGGER__.open`
+No | `rdbg --open --nonstop` | `require "debug/open_nonstop"` | `DEBUGGER__.open(nonstop: true)`
 
 #### `rdbg --open` (or `rdbg -O` for short)
 
@@ -346,12 +364,14 @@ You can attach with external debugger frontend with VSCode and Chrome.
 $ rdbg --open=[frontend] target.rb
 ```
 
-will open a debug port and `[frontned]` can attache to the port.
+will open a debug port and `[frontend]` can attach to the port.
 
 Also `open` command allows opening the debug port.
 
 #### VSCode integration
 
+([vscode-rdbg v0.0.9](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) or later is required)
+
 If you don't run a debuggee Ruby process on VSCode, you can attach with VSCode later with the following steps.
 
 `rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
@@ -411,7 +431,7 @@ Note that you can attach with `rdbg --attach` and continue REPL debugging.
 
 #### Chrome DevTool integration
 
-With `rdbg --open=chrome` command will shows the following message.
+With `rdbg --open=chrome` command will show the following message.
 
 ```
 $ rdbg target.rb --open=chrome
@@ -427,7 +447,7 @@ Type `devtools://devtools/bundled/inspector.html?ws=127.0.0.1:43633` in the addr
 
 Also `open chrome` command works like `open vscode`.
 
-For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/)
+For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/).
 
 ## Configuration
 
@@ -448,41 +468,53 @@ config set no_color true
 
 * UI
   * `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
-  * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10 lines)
-  * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2 frames)
-  * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb)
+  * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10)
+  * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2)
+  * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb) (default: false)
   * `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
   * `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
   * `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
+  * `RUBY_DEBUG_NO_HINT` (`no_hint`): Do not show the hint on the REPL (default: false)
 
 * CONTROL
-  * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths (default: [])
+  * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths
   * `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
   * `RUBY_DEBUG_KEEP_ALLOC_SITE` (`keep_alloc_site`): Keep allocation site and p, pp shows it (default: false)
   * `RUBY_DEBUG_POSTMORTEM` (`postmortem`): Enable postmortem debug (default: false)
   * `RUBY_DEBUG_FORK_MODE` (`fork_mode`): Control which process activates a debugger after fork (both/parent/child) (default: both)
-  * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: disabled)
+  * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: false)
 
 * BOOT
-  * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode
-  * `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location
+  * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode (default: false)
+  * `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location (default: false)
   * `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
   * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. commands should be separated by ';;'
-  * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb)
+  * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb) (default: false)
   * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ~/.rdbg_history)
-  * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10,000)
+  * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10000)
 
 * REMOTE
   * `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
-  * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (localhost if not given)
+  * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (default: 127.0.0.1)
   * `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
   * `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
+  * `RUBY_DEBUG_LOCAL_FS_MAP` (`local_fs_map`): Specify local fs map
+  * `RUBY_DEBUG_SKIP_BP` (`skip_bp`): Skip breakpoints if no clients are attached (default: false)
   * `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
   * `RUBY_DEBUG_OPEN_FRONTEND` (`open_frontend`): frontend used by open command (vscode, chrome, default: rdbg).
+  * `RUBY_DEBUG_CHROME_PATH` (`chrome_path`): Platform dependent path of Chrome (For more information, See [here](https://github.com/ruby/debug/pull/334/files#diff-5fc3d0a901379a95bc111b86cf0090b03f857edfd0b99a0c1537e26735698453R55-R64))
 
 * OBSOLETE
   * `RUBY_DEBUG_PARENT_ON_FORK` (`parent_on_fork`): Keep debugging parent process on fork (default: false)
 
+There are other environment variables:
+
+* `NO_COLOR`: If the value is set, set `RUBY_DEBUG_NO_COLOR` ([NO_COLOR: disabling ANSI color output in various Unix commands](https://no-color.org/)).
+* `RUBY_DEBUG_ENABLE`: If the value is `0`, do not enable debug.gem feature.
+* `RUBY_DEBUG_ADDED_RUBYOPT`: Remove this value from `RUBYOPT` at first. This feature helps loading debug.gem with `RUBYOPT='-r debug/...'` and you don't want to derive it to child processes. In this case you can set `RUBY_DEBUG_ADDED_RUBYOPT='-r debug/...'` (same value) and this string will be deleted from `RUBYOPT` at first.
+* `RUBY_DEBUG_EDITOR` or `EDITOR`: An editor used by `edit` debug command.
+* `RUBY_DEBUG_BB`: Define `Kernel#bb` method which is alias of `Kernel#debugger`.
+
 ### Initial scripts
 
 If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
@@ -525,7 +557,7 @@ The `<...>` notation means the argument.
 * `fin[ish]`
   * Finish this frame. Resume the program until the current frame is finished.
 * `fin[ish] <n>`
-  * Finish frames, same as `step <n>`.
+  * Finish `<n>`th frames.
 * `c[ontinue]`
   * Resume the program.
 * `q[uit]` or `Ctrl-D`
@@ -533,11 +565,11 @@ The `<...>` notation means the argument.
 * `q[uit]!`
   * Same as q[uit] but without the confirmation prompt.
 * `kill`
-  * Stop the debuggee process with `Kernal#exit!`.
+  * Stop the debuggee process with `Kernel#exit!`.
 * `kill!`
   * Same as kill but without the confirmation prompt.
 * `sigint`
-  * Execute SIGINT handler registerred by the debuggee.
+  * Execute SIGINT handler registered by the debuggee.
   * Note that this command should be used just after stop by `SIGINT`.
 
 ### Breakpoint
@@ -558,14 +590,32 @@ The `<...>` notation means the argument.
   * break and run `<command>` before stopping.
 * `b[reak] ... do: <command>`
   * break and run `<command>`, and continue.
+* `b[reak] ... path: <path>`
+  * break if the path matches to `<path>`. `<path>` can be a regexp with `/regexp/`.
 * `b[reak] if: <expr>`
   * break if: `<expr>` is true at any lines.
   * Note that this feature is super slow.
 * `catch <Error>`
   * Set breakpoint on raising `<Error>`.
+* `catch ... if: <expr>`
+  * stops only if `<expr>` is true as well.
+* `catch ... pre: <command>`
+  * runs `<command>` before stopping.
+* `catch ... do: <command>`
+  * stops and run `<command>`, and continue.
+* `catch ... path: <path>`
+  * stops if the exception is raised from a `<path>`. `<path>` can be a regexp with `/regexp/`.
 * `watch @ivar`
   * Stop the execution when the result of current scope's `@ivar` is changed.
   * Note that this feature is super slow.
+* `watch ... if: <expr>`
+  * stops only if `<expr>` is true as well.
+* `watch ... pre: <command>`
+  * runs `<command>` before stopping.
+* `watch ... do: <command>`
+  * stops and run `<command>`, and continue.
+* `watch ... path: <path>`
+  * stops if the path matches `<path>`. `<path>` can be a regexp with `/regexp/`.
 * `del[ete]`
   * delete all breakpoints.
 * `del[ete] <bpnum>`
@@ -604,8 +654,8 @@ The `<...>` notation means the argument.
   * Show information about accessible constants except toplevel constants.
 * `i[nfo] g[lobal[s]]`
   * Show information about global variables
-* `i[nfo] ... </pattern/>`
-  * Filter the output with `</pattern/>`.
+* `i[nfo] ... /regexp/`
+  * Filter the output with `/regexp/`.
 * `i[nfo] th[read[s]]`
   * Show all threads (same as `th[read]`).
 * `o[utline]` or `ls`
@@ -656,8 +706,8 @@ The `<...>` notation means the argument.
   * Add an exception tracer. It indicates raising exceptions.
 * `trace object <expr>`
   * Add an object tracer. It indicates that an object by `<expr>` is passed as a parameter or a receiver on method call.
-* `trace ... </pattern/>`
-  * Indicates only matched events to `</pattern/>` (RegExp).
+* `trace ... /regexp/`
+  * Indicates only matched events to `/regexp/`.
 * `trace ... into: <file>`
   * Save trace information into: `<file>`.
 * `trace off <num>`

data/Rakefile

@@ -1,12 +1,6 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
 begin
   require "rake/extensiontask"
   task :build => :compile
@@ -17,8 +11,7 @@ begin
 rescue LoadError
 end
 
-
-task :default => [:clobber, :compile, 'README.md', :test]
+task :default => [:clobber, :compile, 'README.md', :check_readme, :test_console]
 
 file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
                      'exe/rdbg', 'misc/README.md.erb'] do
@@ -28,7 +21,32 @@ file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
   puts 'README.md is updated.'
 end
 
-task :run => :compile do
-  system(RbConfig.ruby, *%w(-I ./lib test.rb))
+task :check_readme do
+  require_relative 'lib/debug/session'
+  require 'erb'
+  current_readme = File.read("README.md")
+  generated_readme = ERB.new(File.read('misc/README.md.erb')).result
+
+  if current_readme != generated_readme
+    fail <<~MSG
+      The content of README.md doesn't match its template and/or source.
+      Please apply the changes to info source (e.g. command comments) or the template and run 'rake README.md' to update README.md.
+    MSG
+  end
+end
+
+desc "Run all debugger console related tests"
+Rake::TestTask.new(:test_console) do |t|
+  t.test_files = FileList["test/console/*_test.rb", "test/support/*_test.rb"]
+end
+
+desc "Run all debugger protocols (CAP & DAP) related tests"
+Rake::TestTask.new(:test_protocol) do |t|
+  t.test_files = FileList["test/protocol/*_test.rb"]
+end
+
+task test: 'test_console' do
+  warn '`rake test` doesn\'t run protocol tests. Use `rake test-all` to test all.'
 end
 
+task test_all: [:test_console, :test_protocol]

data/debug.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["ko1@atdot.net"]
 
   spec.summary       = %q{Debugging functionality for Ruby}
-  spec.description   = %q{Debugging functionality for Ruby. This is completely rewritten debug.rb which was contained by the encient Ruby versions.}
+  spec.description   = %q{Debugging functionality for Ruby. This is completely rewritten debug.rb which was contained by the ancient Ruby versions.}
   spec.homepage      = "https://github.com/ruby/debug"
   spec.licenses      = ["Ruby", "BSD-2-Clause"]
   spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
@@ -17,14 +17,16 @@ Gem::Specification.new do |spec|
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
   end
   spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
   spec.extensions    = ['ext/debug/extconf.rb']
 
   spec.add_dependency "irb", ">= 1.3.6" # for its color_printer class, which was added after 1.3
-  spec.add_dependency "reline", ">= 0.2.7"
+  spec.add_dependency "reline", ">= 0.3.1"
 end