rspec-context_helper 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74d51db0cb19ab254e02862acae935baf036b6309e65211a92b5447e9bbdd073
+  data.tar.gz: 1cf6b1ff42898e24569fa31c71a2205c76ae6080959617c5bfd99a522ae2ea8f
+SHA512:
+  metadata.gz: cd5d107a0e450bb619a00265063f90f83629178212bac185ff9984ac6b2df955930aaa9821497a731fe63e97b0e394181bcbcc1cceddd721b8dbf401b957e982
+  data.tar.gz: 8db3088d169d05a35be6fbb585839e28e34785b55edf706587fdbefb31ae74176243c1a2cb471fe28e013732c81b47ddc889a379410bd30abdf994328045d636

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.7
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.2.0](https://github.com/masaakiaoyagi/rspec-context_helper.rb/compare/v0.1.0...v0.2.0) (2022-06-09)
+
+
+### Features
+
+* add docker files for testing ([58bec40](https://github.com/masaakiaoyagi/rspec-context_helper.rb/commit/58bec4016b8e2df3cb76ead1078a5c753045a93a))
+* change metadata and shared context parameter name ([cdb9d17](https://github.com/masaakiaoyagi/rspec-context_helper.rb/commit/cdb9d17ddfdfefb483bd22568f480cce5fc9cc52))
+* implement context helper ([aabae85](https://github.com/masaakiaoyagi/rspec-context_helper.rb/commit/aabae8551fc945f7b1a90230426bd4c350a871aa))
+* implement metadata and shared optiions ([8f1a8fa](https://github.com/masaakiaoyagi/rspec-context_helper.rb/commit/8f1a8fa68ef55db10eaa9d9c47926f70a65603ef))
+
+
+### Bug Fixes
+
+* fix to pass _meta and _shared parameters correctly ([2fc7099](https://github.com/masaakiaoyagi/rspec-context_helper.rb/commit/2fc7099f7253f08d8d22dbc2ab00ebd7be875585))
+* remove pry-byebug dependency ([c0ca561](https://github.com/masaakiaoyagi/rspec-context_helper.rb/commit/c0ca561655a59fb4f3be1e4d1932a54da3a94743))

data/Dockerfile

@@ -0,0 +1,43 @@
+ARG RUBY_VERSION
+
+FROM ruby:${RUBY_VERSION}-slim
+
+ARG GROUPNAME=docker
+ARG USERNAME=docker
+ARG UID
+ARG GID
+ARG RUNTIME_PACKAGES="git less"
+ARG BUILD_PACKAGES="build-essential"
+ARG WORKSPACE_DIR=/workspace
+ARG WORKSPACE_CONTAINER_DIR=/workspace-container
+
+RUN set -x \
+ && groupadd -g ${GID} ${GROUPNAME} \
+ && useradd -u ${UID} -g ${GROUPNAME} -m ${USERNAME}
+
+RUN set -x \
+ && apt-get -y update \
+ && apt-get -y upgrade \
+ && apt-get -y install --no-install-recommends ${RUNTIME_PACKAGES} ${BUILD_PACKAGES}
+
+RUN set -x \
+ && mkdir -p ${WORKSPACE_DIR} \
+ && chown -R ${UID}:${GID} ${WORKSPACE_DIR}
+WORKDIR ${WORKSPACE_DIR}
+
+RUN set -x \
+ && mkdir -p ${WORKSPACE_CONTAINER_DIR} \
+ && chown -R ${UID}:${GID} ${WORKSPACE_CONTAINER_DIR}
+
+COPY --chown=${UID}:${GID} . .
+
+USER ${UID}
+
+RUN set -x \
+ && gem install bundler \
+ && bundle config path ${WORKSPACE_CONTAINER_DIR}/vendor/bundle \
+ && bundle install \
+ && mv Gemfile.lock ${WORKSPACE_CONTAINER_DIR}
+
+ENV WORKSPACE_CONTAINER_DIR=${WORKSPACE_CONTAINER_DIR}
+ENTRYPOINT ["/workspace/entrypoint.sh"]

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rspec-context_helper.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"
+
+gem "pry-byebug"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Masaaki Aoyagi <masaaki.aoyagi@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,276 @@
+# RSpec::ContextHelper
+
+https://github.com/masaakiaoyagi/rspec-context_helper.rb/releases[image:https://img.shields.io/github/v/release/masaakiaoyagi/rspec-context_helper.rb?include_prereleases[GitHub release (latest SemVer including pre-releases)]]
+https://github.com/masaakiaoyagi/rspec-context_helper.rb/actions/workflows/test.yml[image:https://github.com/masaakiaoyagi/rspec-context_helper.rb/actions/workflows/test.yml/badge.svg[test]]
+https://opensource.org/licenses/MIT[image:https://img.shields.io/badge/License-MIT-yellow.svg[License: MIT]]
+https://conventionalcommits.org[image:https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white[Conventional Commits]]
+
+This helper library is for writing tests concisely.
+
+You can write a test as follows.
+```ruby
+example_with("value is zero", value: 0) { expect(value).to eq 0 }
+```
+Above is the same as below.
+```ruby
+context "value is zero" do
+  let(:value) { 0 }
+  it { expect(value).to eq 0 }
+end
+```
+
+That's basically all there is to it, but I think it will be more potent when used with a https://relishapp.com/rspec/rspec-expectations/v/3-11/docs/custom-matchers[custom matcher].
+
+.Example of ActiveModel validation tests using a custom matcher
+[%collapsible]
+====
+```ruby
+class Account
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+  attribute :name, :string
+  validates :name, presence: true, length: { in: 3..20 }, format: { with: /\A[0-9a-zA-Z]*\z/, message: "alphanumeric characters only" }
+end
+
+let(:account) { Account.new(name: name) }
+before do
+  account.valid?
+end
+
+# There is no "have_error" matcher, so you need to create one.
+example_with(name: " ")      { expect(account).to have_error.on(:name).with(:blank) }
+example_with(name: "a" * 2)  { expect(account).to have_error.on(:name).with(:too_short, count: 3) }
+example_with(name: "a" * 3)  { expect(account).not_to have_error }
+example_with(name: "a" * 20) { expect(account).not_to have_error }
+example_with(name: "a" * 21) { expect(account).to have_error.on(:name).with(:too_long, count: 20) }
+example_with(name: "a0a")    { expect(account).not_to have_error }
+example_with(name: "a a")    { expect(account).to have_error.on(:name).with(:invalid) }
+example_with(name: "a@a")    { expect(account).to have_error.on(:name).with("alphanumeric characters only") }
+```
+====
+
+## Installation
+
+. Add the dependency to your `Gemfile`:
++
+```ruby
+group :test do
+  gem "rspec-context_helper"
+end
+```
+
+. Run `bundle install`
+
+## Usage
+
+```ruby
+require "rspec-context_helper"
+```
+
+See https://github.com/masaakiaoyagi/rspec-context_helper.rb/blob/main/spec/rspec/context_helper_spec.rb[spec] how to write a test.
+
+### API
+
+#### `example_with(description = nil, _meta: nil, _shared: nil, **values, &block)`
+Defines an exmaple with metadata, shared context and local variables.
+
+##### parameters
+.`description`: context description
+[%collapsible]
+====
+If description is omitted, it is automatically generated from other parameters.
+====
+
+.`_meta`: https://relishapp.com/rspec/rspec-core/v/3-11/docs/metadata/user-defined-metadata[metadata] to be defined
+[%collapsible]
+====
+.examples
+```ruby
+_meta: :foo
+_meta: [:foo, :bar]
+_meta: { foo: "1" }
+_meta: [:foo, bar: 2]
+```
+====
+
+.`_shared`: https://relishapp.com/rspec/rspec-core/v/3-11/docs/example-groups/shared-context[shared context] to be included
+[%collapsible]
+====
+.examples
+```ruby
+_shared: :foo
+_shared: [:foo, :bar]
+_shared: { foo: "1" }
+_shared: [:foo, bar: 2]
+_shared: { foo: [:arg1, :arg2] }
+_shared: { foo: { opt1: :bar } }
+_shared: { foo: [:arg1, opt1: :bar] }
+```
+====
+
+.`values`: helper methods to be defined by https://relishapp.com/rspec/rspec-core/v/3-11/docs/helper-methods/let-and-let[let]
+[%collapsible]
+====
+.You need to use a proc in order to call helper methods in the example context.
+[%collapsible]
+=====
+```ruby
+example_with(foo: bar, bar: 2) { expect(foo).to eq 2 }
+# => undefined local variable or method `bar'
+example_with(foo: -> { bar }, bar: 2) { expect(foo).to eq 2 }
+# => OK
+```
+=====
+
+.So you need to use a *nested* proc in order to define a helper method that returns a proc.
+[%collapsible]
+=====
+```ruby
+example_with(foo: -> { "proc" }) { expect(foo.call).to eq "proc" }
+# => undefined method `call' for "proc":String
+example_with(foo: -> { -> { "proc" } }) { expect(foo.call).to eq "proc" }
+# => OK
+```
+=====
+
+.examples
+```ruby
+foo: "1"
+foo: "1", bar: 2
+foo: -> { bar }, bar: 2
+foo: -> { -> { "proc" } }
+```
+====
+
+##### examples
+.`example_with("description") { expect(true).to eq true }`
+[%collapsible]
+====
+same as
+```ruby
+context "description" do
+  it { expect(true).to eq true }
+end
+```
+====
+
+.`example_with(value: 1) { expect(value).to eq 1 }`
+[%collapsible]
+====
+same as
+```ruby
+context "when value is 1" do
+  let(:value) { 1 }
+  it { expect(value).to eq 1 }
+end
+```
+====
+
+.`example_with(_shared: "logged in") { expect(logged_in).to eq true }`
+[%collapsible]
+====
+same as
+```ruby
+context "when logged in" do
+  include_context "logged in"
+  it { expect(logged_in).to eq true }
+end
+```
+====
+
+.`example_with(_meta: :bar) { |e| expect(e.metadata[:bar]).to eq true }`
+[%collapsible]
+====
+same as
+```ruby
+context "", :bar do
+  it { |e| expect(e.metadata[:bar]).to eq true }
+end
+```
+====
+
+.`example_with(_meta: { foo: 1 }) { |e| expect(e.metadata[:foo]).to eq 1 }`
+[%collapsible]
+====
+same as
+```ruby
+context "", foo: 1 do
+  it { |e| expect(e.metadata[:foo]).to eq 1 }
+end
+```
+====
+
+#### `context_with(description = nil, _meta: nil, _shared: nil, **values, &block)`
+Defines an example group with metadata, shared context and local variables.
+
+##### parameters
+same as `example_with`
+
+##### examples
+.`context_with("description") { ... }`
+[%collapsible]
+====
+same as
+```ruby
+context "description" do
+  ...
+end
+```
+====
+
+.`context_with(value: 1) { ... }`
+[%collapsible]
+====
+same as
+```ruby
+context "when value is 1" do
+  let(:value) { 1 }
+  ...
+end
+```
+====
+
+.`context_with(_shared: "logged in") { ... }`
+[%collapsible]
+====
+same as
+```ruby
+context "when logged in" do
+  include_context "logged in"
+  ...
+end
+```
+====
+
+.`context_with(_meta: :bar) { ... }`
+[%collapsible]
+====
+same as
+```ruby
+context "", :bar do
+  ...
+end
+```
+====
+
+.`context_with(_meta: { foo: 1 }) { ... }`
+[%collapsible]
+====
+same as
+```ruby
+context "", foo: 1 do
+  ...
+end
+```
+====
+
+## Development
+
+### Run tests
+```sh
+$ docker compose run --rm 3.1 bundle exec rspec
+```
+
+## See also
+* https://github.com/rspec/rspec-metagem[RSpec]
+* https://github.com/masaakiaoyagi/spectator-context_helper.cr[Crystal version]

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docker-compose.yml

@@ -0,0 +1,37 @@
+x-base:
+  base: &base
+    build: &build
+      context: .
+      args: &build-args
+        UID: 1000
+        GID: 1000
+    volumes:
+      - .:/workspace
+
+services:
+  "3.1":
+    <<: *base
+    image: rspec-context_helper.rb:3.1
+    build:
+      <<: *build
+      args:
+        <<: *build-args
+        RUBY_VERSION: 3.1
+
+  "3.0":
+    <<: *base
+    image: rspec-context_helper.rb:3.0
+    build:
+      <<: *build
+      args:
+        <<: *build-args
+        RUBY_VERSION: 3.0
+
+  "2.7":
+    <<: *base
+    image: rspec-context_helper.rb:2.7
+    build:
+      <<: *build
+      args:
+        <<: *build-args
+        RUBY_VERSION: 2.7

data/docs/workflow.md

@@ -0,0 +1,52 @@
+# Workflow
+
+## Development
+
+```mermaid
+gitGraph
+
+commit tag: "v0.0.1"
+    branch develop order: 3
+    commit
+    commit
+      branch feature order: 4
+      commit
+      commit
+    checkout develop
+    merge feature
+checkout main
+merge develop
+  branch release-please order: 2
+  commit
+checkout main
+merge release-please tag: "v0.0.2"
+```
+
+### Release
+
+```mermaid
+sequenceDiagram
+
+actor user as Developer
+participant main as GitHub<br />main Branch
+participant pr as GitHub<br />Pull Request
+participant release as GitHub<br />Release
+participant runner as GitHub<br />Actions Runner
+participant gem as rubygems.org
+
+user ->> main: push
+  main -->> runner: run release-please workflow
+        runner -->> release: look for latest release
+          Note over runner: update version
+  runner -->> main: collect commits since all latest releases
+          Note over runner: update CHANGELOG
+    runner -->> pr: create PR
+user ->> gem: disable MFA
+user ->> pr: merge
+  pr -->> main: merge PR
+  main -->> runner: run release-please workflow
+    runner -->> release: create Release
+          Note over runner: create gem
+          runner -->> gem: publish gem
+user ->> gem: enable MFA
+```

data/entrypoint.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+cleanup() {
+  rm Gemfile.lock
+}
+trap cleanup EXIT
+
+ln -sf ${WORKSPACE_CONTAINER_DIR}/Gemfile.lock .
+$@

data/lib/rspec/context_helper/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module ContextHelper
+    VERSION = "0.2.0"
+  end
+end

data/lib/rspec/context_helper.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "rspec"
+
+require_relative "context_helper/version"
+
+module RSpec
+  module ContextHelper
+    module DSL
+      def example_with(description = nil, _meta: nil, _shared: nil, **values, &block)
+        context_with(description, _meta: _meta, _shared: _shared, **values) do
+          example { |*args| instance_exec(*args, &block) }
+        end
+      end
+
+      def context_with(description = nil, _meta: nil, _shared: nil, **values, &block)
+        tags, metadata = Utils.split_options(_meta)
+        shared = Utils.to_h(_shared)
+        description ||= Utils.to_description(tags, metadata, shared, values)
+
+        context description, *tags, **metadata do
+          shared.each do |name, _args|
+            args, opts = Utils.split_options(_args)
+            include_context name, *args, **opts
+          end
+          values.each do |key, value|
+            let(key) do
+              value.is_a?(::Proc) ? instance_exec(&value) : value
+            end
+          end
+          instance_exec(&block)
+        end
+      end
+    end
+
+    module Utils
+      class << self
+        def split_options(value)
+          if value.is_a?(::Hash)
+            [[], value]
+          else
+            value = Array(value)
+            value.last.is_a?(::Hash) ? [value, value.pop] : [value, {}]
+          end
+        end
+
+        def to_h(value)
+          case value
+          when nil
+            {}
+          when ::Array
+            *rest, last = value
+            if last.is_a?(::Hash)
+              rest.map { |i| [i, nil] }.to_h.merge(last)
+            else
+              value.map { |i| [i, nil] }.to_h
+            end
+          when ::Hash
+            value
+          else
+            { value => nil }
+          end
+        end
+
+        def to_description(tags, metadata, shared, values)
+          to_sentence(to_tag_words(tags) + to_metadata_words(metadata) + to_shared_words(shared) + to_values_words(values)).then do |desc|
+            desc.empty? ? desc : "when #{desc}"
+          end
+        end
+
+        # TODO: whether to include tag in the description
+        private def to_tag_words(tags)
+          []
+        end
+
+        # TODO: whether to include metadata in the description
+        private def to_metadata_words(metadata)
+          []
+        end
+
+        private def to_shared_words(shared)
+          shared.map { |k, v| k }
+        end
+
+        private def to_values_words(values)
+          values.map { |k, v| "#{k} is #{v.inspect}" }
+        end
+
+        private def to_sentence(words)
+          case words.size
+          when 0
+            ""
+          when 1
+            words[0]
+          when 2
+            words.join(" and ")
+          else
+            *rest, last = words
+            [rest.join(", "), last].join(" and ")
+          end
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.extend RSpec::ContextHelper::DSL
+end

data/sig/rspec/context_helper.rbs

@@ -0,0 +1,6 @@
+module RSpec
+  module ContextHelper
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: rspec-context_helper
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Masaaki Aoyagi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-06-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: context helpers for RSpec
+email:
+- masaaki.aoyagi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Dockerfile
+- Gemfile
+- LICENSE.txt
+- README.adoc
+- Rakefile
+- docker-compose.yml
+- docs/workflow.md
+- entrypoint.sh
+- lib/rspec/context_helper.rb
+- lib/rspec/context_helper/version.rb
+- sig/rspec/context_helper.rbs
+homepage: https://github.com/masaakiaoyagi/rspec-context_helper.rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/masaakiaoyagi/rspec-context_helper.rb
+  source_code_uri: https://github.com/masaakiaoyagi/rspec-context_helper.rb
+  changelog_uri: https://github.com/masaakiaoyagi/rspec-context_helper.rb/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: context helpers for RSpec
+test_files: []