solargraph-rspec 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b218c57b18c9c34c920dc8085633940b40980109acc0767e3819f2f460af7598
-  data.tar.gz: 8d33d3922c38de08dde380776138fb2eddee93f72aaaee1cd7ae4dce7610ac69
+  metadata.gz: f674511062484768d92fcae50b6f005a941e62933e08d8d0e1bd7d90ebb6751f
+  data.tar.gz: 84ca708c2c86a22cc6345763c4232a550298b1f65bb958f361aeee5e217adda4
 SHA512:
-  metadata.gz: 0d6afb3098eeaa24b1c169ba6993306b14008837ebfd267c30bfe74788cd5deecb7985d33037984f5ed698d259daf9c698dba19f4eed0e6a346f521f081a2d7a
-  data.tar.gz: 88699cf9f89421e1a0306d37ce912c1a1fc231cd722cc4338ec757efed7ca304791b1c2e3e3271b9cb057efe91f2d3db8fa22c70739b88569a0be59c9b0de229
+  metadata.gz: a5cb45cfec11d259c0ffd0d45b52027c64879115b34b8d857dbacfca12dbbd2a9c31ff2d68570dc9c269b3bfd1063e8dd799715250b172ac06685a732f85d4f2
+  data.tar.gz: 8a036f8b0c0fa38ebdde162df6715230edcc6b54d001daaaddc13e1793313a63dbdab2e968355c9eb16eef50b169b5543d583480ac49d23a25d60515f40cbb3f

data/.rubocop.yml

@@ -13,6 +13,9 @@ Style/StringLiteralsInInterpolation:
 Style/Documentation:
   Enabled: false
 
+Style/StructInheritance:
+  Enabled: false
+
 Layout/LineLength:
   Max: 120
 

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## v.0.4.0 - 2024-08-25
+
+### Added
+
+- Support for 3rd party helpers from most known RSpec extension libraries.
+  - [rspec-mocks](https://github.com/rspec/rspec-mocks)
+  - [rspec-rails](https://github.com/rspec/rspec-rails)
+  - [webmock](https://github.com/bblimke/webmock)
+  - [shoulda-matchers](https://matchers.shoulda.io/)
+  - [rspec-sidekiq](https://github.com/wspurgin/rspec-sidekiq)
+  - [airborne](https://github.com/brooklynDev/airborne)
+  - <details><summary>📸</summary>
+    <img src="./doc/images/3rd_party_matchers.png" width="600" alt="3rd party matchers completion">
+    </details>
+
+- Implement RSpec [one-liner syntax](https://rspec.info/features/3-12/rspec-core/subject/one-liner-syntax/) helpers: `is_expected`, `should` and `should_not`
+  - <details><summary>📹</summary>
+    <img src="./doc/images/one_liners_demo.gif" width="600" alt="One-liner syntax completion">
+    </details>
+
+## v0.3.0 - 2024-07-10
+
+### Added
+
+- Added `example_methods` as a configuration option to add your own example methods. (thanks to [@mskog](https://github.com/mskog) - first code contributor 🎉)
+
+## v0.2.2 - 2024-06-23
+
 ### Fixed
 
 - Suggest keeping `spec/**/*` in the `exclude` section of `.solargraph.yml` to avoid performance issues (see [commit](https://github.com/lekemula/solargraph-rspec/commit/3f0fc39e59e99bf9430e55c52ecb88650e49315e))

data/README.md

@@ -7,17 +7,24 @@
 
 RSpec is a testing framework of choice for many Ruby developers. But at the same time is highly dynamic and heavily relying on metaprogramming making it hard to provide accurate code completion and type inference. 
 
-This gem aims to provide better support for RSpec in Solargraph and it supports the following features:
-  - `describe` and `it` methods completion
-  - memoized `let` and `let!` methods completion 
-  - implicit and explicit `subject` methods
+This gem aims to provide better support for RSpec in Solargraph and it supports the following features (completion, jump to definition and type inference 🚀):
+  - `describe` and `it` methods 
+  - memoized `let` and `let!` methods 
   - `described_class` with appropriate type inference
-  - `RSpec::Matchers` methods completion
-  - type inference 🚀
-  - and more to come...
+  - implicit and explicit `subject` methods
+  - one liner syntax helpers `is_expected`, `should` and `should_not` linked to the appropriate subject
+  - Core and 3rd party spec helpers & matchers
+    - [rspec-mocks](https://github.com/rspec/rspec-mocks)
+    - [rspec-rails](https://github.com/rspec/rspec-rails)
+    - [webmock](https://github.com/bblimke/webmock)
+    - [shoulda-matchers](https://matchers.shoulda.io/)
+    - [rspec-sidekiq](https://github.com/wspurgin/rspec-sidekiq)
+    - [airborne](https://github.com/brooklynDev/airborne)
+  - Custom DSL extensions support (see [Configuration](#configuration) section)
+  - and more to come... ⏲️
 
-![solargraph-rspec-with-types](https://github.com/lekemula/solargraph-rspec/assets/9197495/077e74f8-a800-4e90-8922-fa5351adcda3)
-![solargraph-rspec-with-types-vs-code](https://github.com/lekemula/solargraph-rspec/assets/9197495/6a942460-256d-46ca-82de-9869a65309ec)
+![solargraph-rspec-with-types](./doc/images/vim_demo.gif)
+![solargraph-rspec-with-types-vs-code](./doc/images/vscode_demo.gif)
 
 
 ## Installation
@@ -80,6 +87,19 @@ rspec:
     - let_it_be
 ```
 
+If you have your own custom `example`-like methods like `it`, you can add them to your `.solargraph.yml` file like this:
+
+```yaml
+# .solargraph.yml
+# ...
+rspec:
+  example_methods:
+    - my_it
+```
+
+This is useful if you use gems like [rspec-given](https://github.com/rspec-given/rspec-given) which introduces its own `let` and `example` methods.
+
+
 ### Gem completions
 
 Solargraph utilizes the YARD documentation to provide code completion. If you want to have completion for gems in your project, you can generate YARD documentation for them ([Read more](https://solargraph.org/guides/yard)).

data/lib/solargraph/rspec/annotations.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# @!override ActionController::TestCase::Behavior#request
+#   @return [ActionDispatch::Request]
+#
+# @!override ActionController::TestCase::Behavior#response
+#   @return [ActionDispatch::Response]

data/lib/solargraph/rspec/config.rb

@@ -20,6 +20,11 @@ module Solargraph
         (Rspec::LET_METHODS + additional_let_methods).map(&:to_sym)
       end
 
+      # @return [Array<Symbol>]
+      def example_methods
+        (Rspec::EXAMPLE_METHODS + additional_example_methods).map(&:to_sym)
+      end
+
       private
 
       # @return [Hash]
@@ -32,6 +37,11 @@ module Solargraph
         (rspec_raw_data['let_methods'] || []).map(&:to_sym)
       end
 
+      # @return [Array<Symbol>]
+      def additional_example_methods
+        (rspec_raw_data['example_methods'] || []).map(&:to_sym)
+      end
+
       # @return [Hash]
       def raw_data
         @solargraph_config.raw_data

data/lib/solargraph/rspec/convention.rb

@@ -2,6 +2,7 @@
 
 require_relative 'config'
 require_relative 'spec_walker'
+require_relative 'annotations'
 require_relative 'correctors/context_block_namespace_corrector'
 require_relative 'correctors/example_and_hook_blocks_binding_corrector'
 require_relative 'correctors/described_class_corrector'
@@ -9,12 +10,12 @@ require_relative 'correctors/let_methods_corrector'
 require_relative 'correctors/subject_method_corrector'
 require_relative 'correctors/context_block_methods_corrector'
 require_relative 'correctors/dsl_methods_corrector'
+require_relative 'test_helpers'
 require_relative 'pin_factory'
 
 module Solargraph
   module Rspec
     ROOT_NAMESPACE = 'RSpec::ExampleGroups'
-    HELPER_MODULES = ['RSpec::Matchers'].freeze
     HOOK_METHODS = %w[before after around].freeze
     LET_METHODS = %w[let let!].freeze
     SUBJECT_METHODS = %w[subject subject!].freeze
@@ -83,7 +84,12 @@ module Solargraph
       # @return [Environ]
       def global(_yard_map)
         pins = []
-        pins += include_helper_pins
+        pins += Solargraph::Rspec::TestHelpers.include_helper_pins(
+          root_example_group_namespace_pin: root_example_group_namespace_pin
+        )
+        pins += annotation_pins
+        # TODO: Include gem requires conditionally based on Gemfile definition
+        requires = Solargraph::Rspec::TestHelpers.gem_names
 
         if pins.any?
           Solargraph.logger.debug(
@@ -91,7 +97,9 @@ module Solargraph
           )
         end
 
-        Environ.new(pins: pins)
+        Solargraph.logger.debug "[RSpec] added requires #{requires}"
+
+        Environ.new(requires: requires, pins: pins)
       rescue StandardError => e
         raise e if ENV['SOLARGRAPH_DEBUG']
 
@@ -132,7 +140,7 @@ module Solargraph
           )
         end
 
-        Environ.new(requires: ['rspec'], pins: pins)
+        Environ.new(requires: [], pins: pins)
       rescue StandardError => e
         raise e if ENV['SOLARGRAPH_DEBUG']
 
@@ -144,19 +152,6 @@ module Solargraph
 
       private
 
-      # @param helper_modules [Array<String>]
-      # @param source_map [SourceMap]
-      # @return [Array<Pin::Base>]
-      def include_helper_pins(helper_modules: HELPER_MODULES)
-        helper_modules.map do |helper_module|
-          PinFactory.build_module_include(
-            root_example_group_namespace_pin,
-            helper_module,
-            root_example_group_namespace_pin.location
-          )
-        end
-      end
-
       # @return [Config]
       def config
         self.class.config
@@ -169,6 +164,14 @@ module Solargraph
           location: PinFactory.dummy_location('lib/rspec/core/example_group.rb')
         )
       end
+
+      # @return [Array<Pin::Base>]
+      def annotation_pins
+        ann = File.read("#{File.dirname(__FILE__)}/annotations.rb")
+        source = Solargraph::Source.load_string(ann, 'rspec-annotations.rb')
+        map = Solargraph::SourceMap.map(source)
+        map.pins
+      end
     end
   end
 end

data/lib/solargraph/rspec/correctors/subject_method_corrector.rb

@@ -16,6 +16,7 @@ module Solargraph
 
             subject_pin = rspec_subject_method(namespace_pin, subject_name, location_range, fake_method_ast)
             add_pin(subject_pin)
+            add_pins(one_liner_expectation_pins(subject_pin))
           end
 
           rspec_walker.after_walk do
@@ -23,7 +24,11 @@ module Solargraph
 
             namespace_pin = closest_namespace_pin(namespace_pins, described_class_pin.location.range.start.line)
 
-            add_pin(implicit_subject_pin(described_class_pin, namespace_pin)) if namespace_pin
+            if namespace_pin
+              implicit_subject_pin = implicit_subject_method(described_class_pin, namespace_pin)
+              add_pin(implicit_subject_pin)
+              add_pins(one_liner_expectation_pins(implicit_subject_pin))
+            end
           end
         end
 
@@ -47,7 +52,7 @@ module Solargraph
         # @param described_class_pin [Pin::Method]
         # @param namespace_pin [Pin::Namespace]
         # @return [Pin::Method]
-        def implicit_subject_pin(described_class_pin, namespace_pin)
+        def implicit_subject_method(described_class_pin, namespace_pin)
           described_class = described_class_pin.return_type.first.subtypes.first.name
 
           PinFactory.build_public_method(
@@ -58,6 +63,41 @@ module Solargraph
             scope: :instance
           )
         end
+
+        # @param subject_pin [Pin::Method]
+        # @return [Array<Pin::Method>]
+        def one_liner_expectation_pins(subject_pin)
+          [
+            one_liner_expectation_pin(subject_pin.closure, :is_expected, subject_pin.location),
+            one_liner_expectation_pin(subject_pin.closure, :should, subject_pin.location),
+            one_liner_expectation_pin(subject_pin.closure, :should_not, subject_pin.location)
+          ]
+        end
+
+        # @param namespace_pin [Pin::Namespace]
+        # @param method_name [:is_expected, :should, :should_not]
+        # @param location [Solargraph::Location]
+        # @return [Pin::Method]
+        def one_liner_expectation_pin(namespace_pin, method_name, location)
+          return_type = case method_name
+                        when :is_expected
+                          ['::RSpec::Expectations::ExpectationTarget']
+                        when :should
+                          ['::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher']
+                        when :should_not
+                          ['::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher']
+                        else
+                          raise ArgumentError, "Unknown inline expectation method: #{method_name}"
+                        end
+
+          PinFactory.build_public_method(
+            namespace_pin,
+            method_name.to_s,
+            types: [return_type],
+            location: location,
+            scope: :instance
+          )
+        end
       end
     end
   end

data/lib/solargraph/rspec/spec_walker/node_types.rb

@@ -25,9 +25,10 @@ module Solargraph
         end
 
         # @param ast [RubyVM::AbstractSyntaxTree::Node]
+        # @param config [Config]
         # @return [Boolean]
-        def self.a_example_block?(block_ast)
-          Solargraph::Rspec::EXAMPLE_METHODS.include?(method_with_block_name(block_ast))
+        def self.a_example_block?(block_ast, config)
+          config.example_methods.map(&:to_s).include?(method_with_block_name(block_ast))
         end
 
         # @param ast [RubyVM::AbstractSyntaxTree::Node]

data/lib/solargraph/rspec/spec_walker.rb

@@ -138,7 +138,7 @@ module Solargraph
         end
 
         walker.on :ITER do |block_ast|
-          next unless NodeTypes.a_example_block?(block_ast)
+          next unless NodeTypes.a_example_block?(block_ast, config)
 
           @handlers[:on_example_block].each do |handler|
             handler.call(PinFactory.build_location_range(block_ast))

data/lib/solargraph/rspec/test_helpers.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Rspec
+    class TestHelpers
+      class GemHelpers < Struct.new(:required_gems, :helper_modules, keyword_init: true)
+        # @!attribute [r] required_gems
+        #   @return [Array<String>]
+        # @!attribute [r] helper_modules
+        #   @return [Array<String>]
+      end
+
+      class << self
+        # @return [String]
+        def gem_names
+          GEM_HELPERS.flat_map(&:required_gems)
+        end
+
+        # @return [Array<String>]
+        def helper_module_names
+          GEM_HELPERS.flat_map(&:helper_modules)
+        end
+
+        # @param root_example_group_namespace_pin [Pin::Namespace]
+        # @return [Array<Pin::Reference::Include>]
+        def include_helper_pins(root_example_group_namespace_pin:)
+          Solargraph.logger.debug "[RSpec] adding helper modules #{helper_module_names}"
+          helper_module_names.map do |helper_module|
+            PinFactory.build_module_include(
+              root_example_group_namespace_pin,
+              helper_module,
+              root_example_group_namespace_pin.location
+            )
+          end
+        end
+      end
+
+      GEM_HELPERS = [
+        GemHelpers.new(
+          required_gems: %w[rspec],
+          helper_modules: %w[RSpec::Matchers]
+        ),
+        # https://github.com/rspec/rspec-mocks
+        GemHelpers.new(
+          required_gems: %w[rspec-mocks],
+          helper_modules: %w[RSpec::Mocks::ExampleMethods]
+        ),
+        # @see https://github.com/rspec/rspec-rails#what-tests-should-i-write
+        # @see https://github.com/rspec/rspec-rails#helpful-rails-matchers
+        GemHelpers.new(
+          required_gems: %w[rspec-rails actionmailer activesupport activerecord],
+          helper_modules: [
+            'RSpec::Rails::Matchers',
+            'ActionController::TestCase::Behavior',
+            'ActionMailer::TestCase::Behavior',
+            'ActiveSupport::Testing::Assertions',
+            'ActiveSupport::Testing::TimeHelpers',
+            'ActiveSupport::Testing::FileFixtures',
+            'ActiveRecord::TestFixtures',
+            'ActionDispatch::Integration::Runner',
+            'ActionDispatch::Routing::UrlFor',
+            'ActionController::TemplateAssertions'
+          ]
+        ),
+        # @see https://matchers.shoulda.io/docs/v6.2.0/#matchers
+        GemHelpers.new(
+          required_gems: %w[shoulda-matchers],
+          helper_modules: [
+            'Shoulda::Matchers::ActiveModel',
+            'Shoulda::Matchers::ActiveRecord',
+            'Shoulda::Matchers::ActionController',
+            'Shoulda::Matchers::Routing'
+          ]
+        ),
+        # @see https://github.com/wspurgin/rspec-sidekiq#matchers
+        GemHelpers.new(
+          required_gems: %w[rspec-sidekiq],
+          helper_modules: %w[RSpec::Sidekiq::Matchers]
+        ),
+        # @see https://github.com/bblimke/webmock#examples
+        GemHelpers.new(
+          required_gems: %w[webmock],
+          helper_modules: %w[WebMock::API WebMock::Matchers]
+        ),
+        # @see https://github.com/brooklynDev/airborne
+        GemHelpers.new(
+          required_gems: %w[airborne],
+          helper_modules: %w[Airborne]
+        )
+      ].freeze
+    end
+  end
+end

data/lib/solargraph/rspec/version.rb

@@ -2,6 +2,6 @@
 
 module Solargraph
   module Rspec
-    VERSION = '0.2.2'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,35 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: solargraph-rspec
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Lekë Mula
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-23 00:00:00.000000000 Z
+date: 2024-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: solargraph
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.49'
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.49.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.49'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.49'
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.49.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.49'
 description: RSpec is a testing tool of choice for many Ruby developers. This plugin
   provides code completion and other features for RSpec files in Solargraph.
 email:
@@ -46,7 +46,12 @@ files:
 - README.md
 - Rakefile
 - codecov.yml
+- doc/images/3rd_party_matchers.png
+- doc/images/one_liners_demo.gif
+- doc/images/vim_demo.gif
+- doc/images/vscode_demo.gif
 - lib/solargraph-rspec.rb
+- lib/solargraph/rspec/annotations.rb
 - lib/solargraph/rspec/config.rb
 - lib/solargraph/rspec/convention.rb
 - lib/solargraph/rspec/correctors/base.rb
@@ -63,6 +68,7 @@ files:
 - lib/solargraph/rspec/spec_walker/full_constant_name.rb
 - lib/solargraph/rspec/spec_walker/node_types.rb
 - lib/solargraph/rspec/spec_walker/rspec_context_namespace.rb
+- lib/solargraph/rspec/test_helpers.rb
 - lib/solargraph/rspec/version.rb
 - lib/solargraph/rspec/walker.rb
 - lib/solargraph_rspec.rb
@@ -89,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.0.9
 signing_key:
 specification_version: 4
 summary: Solargraph plugin supporting RSpec code completion