rspec-tapas 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 02d482bfe50d7a8b18f7b7b4c4fca20f55072bb0
-  data.tar.gz: 13460e4cb8ae5f5879c47a909fe855128bc7267b
+  metadata.gz: ac612ac4ea7957a55f94f98fe712c54e47d0e1c0
+  data.tar.gz: e588c6af989d560c2979566309555d4954031029
 SHA512:
-  metadata.gz: 0b635329022669a7a7974a00c5b8b6d8802bc98524c736235855c98249db545db181d2afb3646997904e871a408a1336d1e59fa5ce895a3134314a4e8cea702d
-  data.tar.gz: a7541cb38c463665e958fc46c738a4d29b180e95825ba7f1a71b2244166aaa007d92866aa55644637eff5dff68a165e3a8abd4ec459ff56b51e5ea21685d25b4
+  metadata.gz: 063ab3599b8834d5a79864716c0ae2c2159c95b604f57351fac1fe19899afc7fe3b03b72131053cb97b3279871bd8d064a4f8f90b3c23382e12b85d063a92f28
+  data.tar.gz: 773b4f7ffc6013d08f8eb6ce59d8d89c6e3f715222575a2fea861b123a0d19f370f44adab00e215545f36f1cc8dd2b2e32c86084ab32f4b960ff9a7754e49b61

data/README.md

@@ -0,0 +1,304 @@
+# rspec-tapas
+
+rspec-tapas is a set of small helpers and extensions we often use in [Selleo](https://selleo.com/) when testing our ruby apps.
+
+## Installation
+
+To install rspec-tapas just add following line to your `Gemfile`s `:test` group
+
+```ruby
+gem 'ruby-tapas'
+```
+
+then just `bundle install` and require it in `rails_helper.rb`
+
+```ruby
+require 'rspec_tapas/all'
+```
+
+## Helpers
+
+### StubEnv
+
+`StubEnv` is an extension that allows you to quickly stub values that should be retrieved from `ENV`.
+It is assumed here, that you will use `fetch` method to retrieve such value (so it yields an exception when given ENV is not defined what sounds like a reasonable default).
+
+*Example*
+
+```ruby
+it 'sends a notification after checkout' do
+    stub_env('CHECKOUT_TIME', '13:00')
+    #...
+end
+```
+
+To include this extension only, call `require rspec_tapas/stub_env`
+
+`StubEnv` is accessible in all types of specs
+
+### DateHelpers
+
+`DateHelpers` is a set of two methods that facilitate using `ActiveSupport::Testing::TimeHelpers`. Therefore you need to include `ActiveSupport::Testing::TimeHelpers` in your config if you want to use `DateHelpers`. It is as simple as
+
+```ruby
+RSpec.configure do |config|
+  config.include ActiveSupport::Testing::TimeHelpers
+end
+```
+
+#### at_date
+
+`at_date` runs contents of the block at given date, provided in a format acceptable by `Date.new`. It is basically a shortcut to `travel_to(Date.new(*args)){}`.
+
+*Example*
+
+```ruby
+context 'one day before deadline' do
+    it 'sends a reminder' do
+        #...
+        at_date(2018, 1, 12) do
+            SendPendingReminders.call
+        end
+        #...
+    end
+end
+```
+
+#### freeze_time
+
+`freeze_time` freezes the time and runs contents of the block at. It is basically a shortcut to `travel_to(Time.current){}`.
+
+*Example*
+
+```ruby
+it 'discards records created at the same time' do
+    #...
+    freeze_time do
+      user_1 = create(:user)
+      user_2 = create(:user)
+    end
+    #...
+end
+```
+
+To include this extension only, call `require rspec_tapas/date_helpers`
+
+`DateHelpers` are accessible in all types of specs
+
+### ViewPage
+
+`ViewPage` is a small helper that allows testing views using capybara helpers, usually limited only to feature specs.
+
+*Example*
+
+```ruby
+RSpec.describe 'users/show.html.erb', type: :view do
+  it 'renders user name' do
+    user = create(:user, name: "Tony")
+    allow(view).to receive(:user) { user }
+
+    render
+
+    expect(page).to have_content("Tony")
+  end
+end
+```
+
+To include this extension only, call `require rspec_tapas/view_page`
+
+`ViewPage` is accessible only in view specs
+
+
+### InvokeTask
+
+`InvokeTask` is a small helper that facilitates calling rake tasks when testing them.
+
+*Example*
+
+```ruby
+RSpec.describe 'db:materialize', type: :rake do
+  it 'materializes db view by name' do
+    database = double(:database)
+    allow(Scenic).to receive(:database) { database }
+    allow(database).to receive(:refresh_materialized_view)
+
+    invoke_task('db:materialize', view_name: 'sample_view')
+
+    expect(database).to \
+      have_received(:refresh_materialized_view).with('sample_view')
+  end
+end
+```
+
+To include this extension only, call `require rspec_tapas/invoke_task`
+
+`InvokeTask` is accessible only in rake specs
+
+
+### GetMessagePart
+
+`GetMessagePart` is a set of helpers to facilitate extraction of html/plain parts of emails sent. To extract plaintext part from email, use `text_part(mail)`. To extract HTML part, use `html_part(mail)`.
+
+```ruby
+RSpec.describe ReportMailer, type: :mailer do
+  describe '#summary' do
+    it 'creates email containing orders summary' do
+      create_list(:order, 2)
+      mail = ReportMailer.summary
+
+      expect(mail.subject).to eq('Orders summary')
+      expect(html_part(mail)).to include_html(
+        <<~HTML
+            <h1>Orders summary</h1>
+            <strong>Total orders created:</strong> 2 <br /> 
+        HTML
+      )
+      expect(text_part(mail)).to include('Total orders created: 2')
+    end
+  end
+end
+```
+
+To include this extension only, call `require rspec_tapas/get_message_part`
+
+`GetMessagePart` is accessible only in mailer specs
+
+### JsonResponse
+
+`JsonResponse` is a simple helper that transforms JSON encoded response body to `HashWithIndifferentAccess` or an array of those. This is to facilitate using regular matchers to assert such response.
+
+*Example*
+
+```ruby
+it 'returns user names and emails' do
+  create(:user, name: 'Tony', email: 'tony@stark.dev')
+  create(:user, name: 'Bruce', email: 'bruce@wayne.dev')
+
+  get '/v1/users'
+
+  expect(json_response).to match(
+    data: [
+      { name: 'Tony', email: 'tony@stark.dev' },
+      { name: 'Bruce', email: 'bruce@wayne.dev' },
+    ]
+  )
+end
+```
+
+To include this extension only, call `require rspec_tapas/json_response`
+
+`JsonResponse` is accessible only in request and controller specs
+
+### DownloadsHelpers
+
+`DownloadsHelpers` is a set of two helpers oriented on facilitating testing downloads. First, we need to allow downloading file in given feature spec by calling `allow_file_downloads(page)`. Then, to get downloaded file contents, we need to use `downloaded_file_contents(file_name)` helper.
+
+To allow downloads with headless-chrome capybara driver, we need to configure it in specific way. See example below:
+
+```ruby
+require 'selenium/webdriver'
+
+Capybara.register_driver :headless_chrome do |app|
+  options = Selenium::WebDriver::Chrome::Options.new
+  options.add_argument('--headless')
+  options.add_argument('--no-sandbox')
+  options.add_argument('--disable-gpu')
+  options.add_argument('--disable-popup-blocking')
+  options.add_argument('--window-size=1920,1200')
+  options.add_preference(
+    :download,
+    directory_upgrade: true,
+    prompt_for_download: false,
+    default_directory: RspecExtensions::DownloadsHelpers::DOWNLOADS_PATH
+  )
+  options.add_preference(:browser, set_download_behavior: { behavior: 'allow' })
+
+  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
+end
+
+Capybara.javascript_driver = :headless_chrome
+```
+
+Then, testing downloads is just a matter of few lines of code.
+
+*Example*
+
+```ruby
+allow_file_downloads(page)
+
+click_on 'Download report'
+
+expect(downloaded_file_contents('daily_report.csv')).to eq("Name, Total revenue\nBatman suits, 1000")
+```
+
+To include this extension only, call `require rspec_tapas/downloads_helpers`
+
+`DownloadsHelpers` are accessible only in feature specs
+
+### FeatureHelpers
+
+`FeatureHelpers` module contains a couple of methods useful in features specs.
+
+- `display_logs` will display browser logs in console. This is useful for debugging javascript errors in feature specs.
+- `ss` is a shortcut for `page.save_and_open_screenshot`
+- `reload_page` is a handy shortcut for reloading current page.
+
+To include this extension only, call `require rspec_tapas/feature_helpers`
+
+`FeatureHelpers` are accessible only in feature specs
+
+### BehaviorDSL
+
+`BehaviorDSL` module has two roles. First one is to add some syntactic sugar to feature specs, by introducing additional level of describing context, but without interrupting test. This way you can group actions and assertions in readable blocks.
+
+Second role of `BehaviorDSL` is to add capability of asserting feature - controller integration. This way we can ensure, that given block of capybara interactions were using particular controller action.
+
+*Example*
+
+```ruby
+RSpec.describe 'Users management' do
+  scenario do
+    behavior 'Admin browses existing users', using: 'Admin::UsersController#index' do
+      create(:user, name: 'Luke Cage')
+      create(:unit, name: 'Jessica Jones')
+
+      visit '/admin/users'
+
+      expect(page).to have_row_content('Full name' => 'Luke Cage')
+      expect(page).to have_row_content('Full name' => 'Jessica Jones')
+    end
+
+    behavior 'Admin updates existing user' do
+      #...
+    end
+  end
+end
+```
+
+To include this extension only, call `require rspec_tapas/behavior_dsl`
+
+`BehaviorDSL` is accessible only in feature specs
+
+## Matchers
+
+### have_table_row
+
+`have_table_row` is a matcher dedicated to finding table rows by their values correlated with specific headers. As so, this is mostly useful in feature specs.
+
+*Examples*
+
+```ruby
+# Asserting headers by their names
+expect(page).to have_table_row('First name' => 'Tony', 'Last name' => 'Stark', 'Rating' => 4.5)
+
+# Asserting headers by their indices
+expect(page).to have_table_row(1 => 'Tony', 2 => 'Stark', 3 => 4.5)
+
+# Asserting headers by their indices - shorter version
+expect(page).to have_table_row('Tony', 'Stark', 4.5)
+
+# Composing matchers
+expect(page).to have_table_row(have_content('ny'), 'Stark')
+```
+
+To include this matcher only, call `require rspec_tapas/matchers/have_table_row`

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/rspec_tapas/behavior_dsl.rb

@@ -1,24 +1,40 @@
 module RspecExtensions
   module BehaviorDSL
-    def behavior(name)
-      metadata[:description_args].push(name)
-      refresh_description
-      yield
-      metadata[:description_args].pop
-      refresh_description
+    BehaviorNotification = Struct.new(:message)
+    class BehaviorNotification
+      def execution_result
+        RSpec::Core::Example::ExecutionResult.new
+      end
+
+      def description
+        message
+      end
     end
 
-    private
+    def behavior(name, using: nil)
+      if using.present?
+        @controller_actions_called = []
+        callback = lambda do |*args|
+          options = args.extract_options!
+          @controller_actions_called << "#{options[:controller]}##{options[:action]}"
+        end
+        ActiveSupport::Notifications.subscribed(callback, 'start_processing.action_controller') do
+          yield
+        end
+
+        expect(@controller_actions_called).to(
+          include(using),
+          "expected #{using} to be used for #{name}, but it was not"
+        )
+      else
+        yield
+      end
 
-    def refresh_description
-      metadata[:description] = metadata[:description_args].join(' ')
-      metadata[:full_description] = \
-      [metadata[:example_group][:full_description]].
-        concat(metadata[:description_args]).join(' ')
+      reporter.example_passed(BehaviorNotification.new(name))
     end
 
-    def metadata
-      RSpec.current_example.metadata
+    def reporter
+      RSpec.current_example.reporter
     end
   end
 end

data/rspec-tapas.gemspec

@@ -2,28 +2,28 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: rspec-tapas 0.1.0 ruby lib
+# stub: rspec-tapas 0.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "rspec-tapas".freeze
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["B\u0142a\u017Cej Kosmowski".freeze]
-  s.date = "2018-06-26"
+  s.date = "2018-06-27"
   s.description = "A selection of small rSpec extensions".freeze
   s.email = "b.kosmowski@selleo.com".freeze
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.md",
     "Rakefile",
     "VERSION",
     "lib/rspec-tapas.rb",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tapas
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Błażej Kosmowski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-26 00:00:00.000000000 Z
+date: 2018-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shoulda
@@ -86,13 +86,13 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
-- README.rdoc
+- README.md
 files:
 - ".document"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - lib/rspec-tapas.rb

data/README.rdoc

@@ -1,18 +0,0 @@
-= rspec-tapas
-
-Description goes here.
-
-== Contributing to rspec-tapas
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Start a feature/bugfix branch.
-* Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2018 Błażej Kosmowski. See LICENSE.txt for
-further details.