Allow debugging with vscode (#1517)

* Update CONTRIBUTING.md about Gemfile.local

* Add docs for VSCode users

* Add rspec binstub and sample launch tasks

.gitignore

@@ -17,6 +17,7 @@ target
 *.tmproj
 .#*
 .idea
+.vscode
 *.pyc
 *.rbc
 rerun.txt
@@ -29,6 +30,7 @@ tags
 .ruby-version
 .project
 Gemfile.local
+Gemfile.local.lock
 .envrc
 Gemfile.lock
 bin/json-formatter

.rubocop.yml

@@ -17,6 +17,7 @@ AllCops:
   # `-S/--display-style-guide` option.
   DisplayStyleGuide: true
   Exclude:
+    - 'bin/*'
     - 'tmp/**/*'
     - 'vendor/**/*'
     - 'temp_app/**/*'

CONTRIBUTING.md

@@ -21,17 +21,29 @@ You can chat with the core team on https://gitter.im/cucumber/contributors. We t
 
 ## Installing your own gems
 
-A `Gemfile.local`-file can be used to have your own gems installed to support
-your normal development workflow.
+A `Gemfile.local`-file can be used to have your own gems installed to support your normal development workflow. 
+Execute `bundle config set --local gemfile Gemfile.local` to use it per default.
 
 Example:
 
 ~~~ruby
-gem 'pry'
-gem 'pry-byebug'
-gem 'byebug'
+# Include the regular Gemfile
+eval File.read('Gemfile')
+
+group :development do
+  gem 'byebug'
+  gem 'debase', require: false
+  gem 'ruby-debug-ide', require: false
+  gem 'pry'
+  gem 'pry-byebug'
+end 
 ~~~
 
+## Using Visual Studio Code?
+
+Sample for launch.json configuration is available in
+[docs/vscode-example-launch-configuration.md](https://github.com/cucumber/cucumber-ruby/blob/master/docs/vscode-example-launch-configuration.md)
+
 ## Note on Patches/Pull Requests
 
 * Fork the project. Make a branch for your change.

bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile.local",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

docs/vscode-example-launch-configuration.md

@@ -0,0 +1,94 @@
+## Pre-requisites
+
+### Ruby Extension
+
+Install and configure the
+[ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby)
+
+### Use `debase` and `ruby-debug-ide` gems locally
+
+Make sure to use a `Gemfile.local` file with `debase` and `ruby-debug-ide` gems.
+
+~~~ruby
+# Include the regular Gemfile
+eval File.read('Gemfile')
+
+group :development do
+  gem 'debase', require: false
+  gem 'ruby-debug-ide', require: false
+end 
+~~~
+
+Execute `bundle config set --local gemfile Gemfile.local` to use it per default,
+then `bundle install`.
+
+## Sample launch.json
+
+The following `launch.json` - to be placed in the `.vscode` folder - allows to use
+VSCode debugging features like **breakpoints** and **watches**. 
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Cucumber",
+            "type": "Ruby",
+            "request": "launch",
+            "useBundler": true,
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/cucumber",
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Cucumber current feature file",
+            "type": "Ruby",
+            "request": "launch",
+            "useBundler": true,
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/cucumber",
+            "args": ["${file}"],
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Cucumber scenario under cursor",
+            "type": "Ruby",
+            "request": "launch",
+            "useBundler": true,
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/cucumber",
+            "args": ["${file}:${lineNumber}"],
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Rspec",
+            "type": "Ruby",
+            "request": "launch",
+            "useBundler": true,
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rspec",
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Rspec current file",
+            "type": "Ruby",
+            "request": "launch",
+            "useBundler": true,
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rspec",
+            "args": ["${file}"],
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Rspec current line",
+            "type": "Ruby",
+            "request": "launch",
+            "useBundler": true,
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rspec",
+            "args": ["${file}:${lineNumber}"],
+            "internalConsoleOptions": "openOnSessionStart"
+        }
+    ]
+}
+```

lib/cucumber/formatter/backtrace_filter.rb

@@ -15,6 +15,7 @@ module Formatter
       test/unit
       .gem/ruby
       bin/bundle
+      rdebug-ide
     ]
 
     @backtrace_filters << RbConfig::CONFIG['rubyarchdir'] if RbConfig::CONFIG['rubyarchdir']