dvla-atlas 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 109ee9046094b99c7ccb3fc7b188fcca9240a61ae2d5c2091c4257483b447746
+  data.tar.gz: 0776f0ab8215402924da52459e1336869dcc0bb9cce5288575c71e6a77e22dc0
+SHA512:
+  metadata.gz: 511df857b1ae53375702fa50b65335a98d31a6bb8c163802cac77451cb152fc517770272378c10901a294e4e77d8234add7ae3795679a15e2aa7b0bfc750cd71
+  data.tar.gz: 9312d564d9a86db24cdac3646645fb2fbca4ea996be8c96eaa3902defd6f3036134d5cf5de29d386dce2a7dea10ef7f0cd1ae77a09db6579cca929d4ba560d8d

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 HM Government (Driver and Vehicle Licensing Agency)
+
+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.md

@@ -0,0 +1,153 @@
+# Atlas
+
+Atlas provides a wrapper around the `World` functionality provided by Cucumber. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dvla-atlas'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install dvla-atlas
+
+
+## World overview
+
+World is a [feature of Cucumber](https://github.com/cucumber/cucumber-ruby/blob/main/features/docs/writing_support_code/world.feature) that allows the user to influence the context within which test steps are run. By default, at the start of each scenario Cucumber calls `Object.new` and mixes in the RSpec assertions to get the context within which the test steps will be executed. Calling `World` allows this to be changed in one of two ways.
+
+The first is by defining additional methods within a module and then mixing that into the object that the tests are run in the context of. For example, suppose we define the following module `Helper`:
+
+```ruby
+module Helper
+  def foo
+    'foo'
+  end
+end
+```
+
+If this module is then passed into World (`World(Helper)`), all steps that are run in that test pack will be able to call the method `foo` directly.
+
+The second way to use World is to provide it with a block of code. This block will be called at the start of each Scenario, with the returned value being used in place of `Object.new`. For example, suppose we define the following class `Base`:
+
+```ruby
+class Base
+  def initialize(base_value)
+    @base_value = base_value
+  end
+  
+  def add_to_base_value(value_to_add)
+    value_to_add + @base_value
+  end
+  
+  def set_base_value(new_base_value)
+    @base_value = new_base_value
+  end
+end
+```
+
+The above can be used as the context for all tests with the following code:
+
+```ruby
+World do
+  Base.new(2)
+end
+```
+
+As this is run for each new scenario, the block will be run again and so the internal `base_value` will start off as 2 for each new test.
+
+## Using Atlas
+
+### Adding it to your tests
+
+Atlas functions by providing the base class (in this instance called `TestArtefactory`) for tests to run in the context of. This features a single method called `artefacts` that returns an artefacts object upon which you can define variables that you wish to share across steps within the same scenario. Once you got the gem installed you can add the following to your `env.rb` file (or equivalent):
+
+```ruby
+World do
+  DVLA::Atlas.base_world
+end
+```
+
+However, the generated artefacts does not currently have any fields
+
+### Adding fields to your artefact
+
+For example, if you wanted all scenarios to have access to the string `foo` this could be set up in the following way when creating World:
+
+```ruby
+World do
+  world = DVLA::Atlas.base_world
+  world.artefacts.define_fields(foo: 'foo')
+  world
+end
+```
+
+This would allow any test step to make the following call and retrieve the value of 'foo' in the following way:
+
+```ruby
+artefacts.foo
+```
+
+Additionally, a setter for that variable will also exist, so a test could assign a different value to foo for the rest of the scenario if required, such as:
+
+```ruby
+artefacts.foo = 'bar'
+```
+
+It is also possible to create a variable in artefacts without assigning any value to it. For example, you could have the initial call to World that looks like this:
+
+```ruby
+World do
+  world = DVLA::Atlas.base_world
+  world.artefacts.define_fields('current_url')
+  world
+end
+```
+
+This would guarantee that `current_url` is accessible by all test steps, even if it does not start with a value.
+
+### Exposing your own helper methods
+
+If you've got some of your own helper methods you'd like to make available, you can define them in a module and mix that in with the world. You'd do that in the following way:
+
+```ruby
+World do
+  world = DVLA::Atlas.base_world
+  world.artefacts.define_fields('current_url', 'username', 'password')
+  world
+end
+
+module Helpers
+  def double(value)
+    value * 2
+  end
+end
+
+World(Helpers)
+```
+
+As well as the fields `current_url`, `username` and `password`, this would provide all test steps with access to the method `double`
+
+### Accessing the artefact outside the scope of the test steps
+
+If you need access to the artefact from somewhere other than directly in the steps and it is not feasible to pass it in from step method then it can be configured to be accessible globally. That is achieved by adding a call into `make_artefacts_global` when configuring World:
+
+```ruby
+World do
+  world = DVLA::Atlas.base_world
+  world.artefacts.define_fields('current_url', 'username', 'password')
+  DVLA::Atlas.make_artefacts_global(world.artefacts)
+  world
+end
+```
+
+## Development
+
+Atlas is quite lightweight. The functionality that deals with the creation of properties in with the test artefact is located within `artefacts.rb`. This project uses [Sorbet](https://sorbet.org/) for type checking. When making changes, don't forget to add tests.

data/lib/dvla/atlas/artefacts.rb

@@ -0,0 +1,52 @@
+#typed: strict
+
+require 'sorbet-runtime'
+
+module DVLA
+  module Atlas
+    class Artefacts
+      extend T::Sig
+
+      sig { params(vargs: String, kwargs: T.untyped).void }
+      def define_fields(*vargs, **kwargs)
+        vargs.each do |attr|
+          initialise_fields(attr)
+        end
+
+        kwargs.each_pair do |key, value|
+          initialise_fields(key)
+          send(:"#{key}=", value) # As an initial value has been passed for this field, we want to set it using the newly defined setter
+        end
+      end
+
+    private
+
+      sig { params(name: T.any(String, Symbol)).void }
+      def initialise_fields(name)
+        # Create the history of the newly defined field. This will start out empty. There is no public way to set this so
+        # no need to expose it by defining a method.
+        instance_variable_set("@#{name}_history", [])
+
+        # Create the getter for the new field, and ensure that it is run upon call if it is a proc.
+        define_singleton_method :"#{name}" do
+          value = instance_variable_get("@#{name}")
+          value.respond_to?(:call) ? value.call : value
+        end
+
+        # Define a getter for the history of the new field
+        define_singleton_method :"#{name}_history" do
+          instance_variable_get("@#{name}_history")
+        end
+
+        # Define the setter for the new field. This also pushes the current value of the field into the history unless
+        # it is currently nil and the history is empty. This is to prevent each history list starting with a nil entry
+        # as all fields are nil when defined.
+        define_singleton_method :"#{name}=" do |arg|
+          current_value = send(:"#{name}")
+          send(:"#{name}_history").push(current_value) unless send(:"#{name}_history").empty? && current_value.nil?
+          instance_variable_set("@#{name}", arg)
+        end
+      end
+    end
+  end
+end

data/lib/dvla/atlas/holder.rb

@@ -0,0 +1,22 @@
+#typed: strict
+
+require 'singleton'
+
+module DVLA
+  module Atlas
+    class Holder
+      extend T::Sig
+      include Singleton
+
+      sig { returns(DVLA::Atlas::Artefacts) }
+      attr_accessor :artefacts
+
+      # The below is required by Sorbet. While the flow of the code within Atlas won't allow for :artefacts to be called
+      # externally before something is assigned to it, Sorbet requires that it is initialized using T.let.
+      sig { void }
+      def initialize
+        @artefacts = T.let(DVLA::Atlas::Artefacts.new, DVLA::Atlas::Artefacts)
+      end
+    end
+  end
+end

data/lib/dvla/atlas/test_artefactory.rb

@@ -0,0 +1,13 @@
+#typed: strict
+
+module DVLA
+  module Atlas
+    class TestArtefactory
+      extend T::Sig
+      sig { returns(DVLA::Atlas::Artefacts) }
+      def artefacts
+        @artefacts ||= T.let(Artefacts.new, T.nilable(DVLA::Atlas::Artefacts))
+      end
+    end
+  end
+end

data/lib/dvla/atlas/version.rb

@@ -0,0 +1,5 @@
+module DVLA
+  module Atlas
+    VERSION = '1.0.0'.freeze
+  end
+end

data/lib/dvla/atlas.rb

@@ -0,0 +1,23 @@
+# typed: strict
+
+require 'dvla/atlas/artefacts'
+require 'dvla/atlas/holder'
+require 'dvla/atlas/test_artefactory'
+require 'sorbet-runtime'
+
+module DVLA
+  module Atlas
+    extend T::Sig
+
+    sig { returns(DVLA::Atlas::TestArtefactory) }
+    def self.base_world
+      TestArtefactory.new
+    end
+
+    sig { params(artefacts: DVLA::Atlas::Artefacts).void }
+    def self.make_artefacts_global(artefacts)
+      DVLA::Atlas::Holder.instance.artefacts = artefacts
+      Object.send(:define_method, :artefacts) { DVLA::Atlas::Holder.instance.artefacts }
+    end
+  end
+end

data/sorbet/config

@@ -0,0 +1,3 @@
+--dir
+.
+--ignore=vendor/

data/sorbet/rbi/annotations/activesupport.rbi

@@ -0,0 +1,128 @@
+# typed: strict
+
+# DO NOT EDIT MANUALLY
+# This file was pulled from a central RBI files repository.
+# Please run `bin/tapioca annotations` to update it.
+
+module ActiveSupport::Testing::Declarative
+  sig { params(name: String, block: T.proc.bind(T.untyped).void).void }
+  def test(name, &block); end
+end
+
+class ActiveSupport::EnvironmentInquirer
+  sig { returns(T::Boolean) }
+  def development?; end
+
+  sig { returns(T::Boolean) }
+  def production?; end
+
+  sig { returns(T::Boolean) }
+  def test?; end
+
+  # @method_missing: delegated to String through ActiveSupport::StringInquirer
+  sig { returns(T::Boolean) }
+  def staging?; end
+end
+
+module ActiveSupport::Testing::SetupAndTeardown::ClassMethods
+  sig { params(args: T.untyped, block: T.nilable(T.proc.bind(T.untyped).void)).void }
+  def setup(*args, &block); end
+
+  sig { params(args: T.untyped, block: T.nilable(T.proc.bind(T.untyped).void)).void }
+  def teardown(*args, &block); end
+end
+
+class ActiveSupport::TestCase
+  sig { params(args: T.untyped, block: T.nilable(T.proc.bind(T.attached_class).void)).void }
+  def self.setup(*args, &block); end
+
+  sig { params(args: T.untyped, block: T.nilable(T.proc.bind(T.attached_class).void)).void }
+  def self.teardown(*args, &block); end
+
+  sig { params(name: String, block: T.proc.bind(T.attached_class).void).void }
+  def self.test(name, &block); end
+end
+
+class Object
+  sig { returns(T::Boolean) }
+  def blank?; end
+
+  sig { returns(T::Boolean) }
+  def present?; end
+end
+
+class Hash
+  sig { returns(T::Boolean) }
+  def extractable_options?; end
+end
+
+class Array
+  sig { params(position: Integer).returns(T.self_type) }
+  def from(position); end
+
+  sig { params(position: Integer).returns(T.self_type) }
+  def to(position); end
+
+  sig { params(elements: T.untyped).returns(T::Array[T.untyped]) }
+  def including(*elements); end
+
+  sig { params(elements: T.untyped).returns(T.self_type) }
+  def excluding(*elements); end
+
+  sig { params(elements: T.untyped).returns(T.self_type) }
+  def without(*elements); end
+
+  sig { returns(T.nilable(Elem)) }
+  def second; end
+
+  sig { returns(T.nilable(Elem)) }
+  def third; end
+
+  sig { returns(T.nilable(Elem)) }
+  def fourth; end
+
+  sig { returns(T.nilable(Elem)) }
+  def fifth; end
+
+  sig { returns(T.nilable(Elem)) }
+  def forty_two; end
+
+  sig { returns(T.nilable(Elem)) }
+  def third_to_last; end
+
+  sig { returns(T.nilable(Elem)) }
+  def second_to_last; end
+
+  sig { params(options: T::Hash[T.untyped, T.untyped]).returns(String) }
+  def to_sentence(options = {}); end
+
+  sig { params(format: Symbol).returns(String) }
+  def to_fs(format = :default); end
+
+  sig { params(format: Symbol).returns(String) }
+  def to_formatted_s(format = :default); end
+
+  sig { returns(String) }
+  def to_xml; end
+
+  sig { returns(T::Hash[T.untyped, T.untyped]) }
+  def extract_options!; end
+
+  sig { type_parameters(:FillType).params(number: Integer, fill_with: T.type_parameter(:FillType), block: T.nilable(T.proc.params(group: T::Array[T.any(Elem, T.type_parameter(:FillType))]).void)).returns(T::Array[T::Array[T.any(Elem, T.type_parameter(:FillType))]]) }
+  def in_groups(number, fill_with = T.unsafe(nil), &block); end
+
+  sig { type_parameters(:FillType).params(number: Integer, fill_with: T.type_parameter(:FillType), block: T.nilable(T.proc.params(group: T::Array[T.any(Elem, T.type_parameter(:FillType))]).void)).returns(T::Array[T::Array[T.any(Elem, T.type_parameter(:FillType))]]) }
+  def in_groups_of(number, fill_with = T.unsafe(nil), &block); end
+
+  sig { params(value: T.untyped, block: T.nilable(T.proc.params(element: Elem).returns(T.untyped))).returns(T::Array[T::Array[Elem]]) }
+  def split(value = nil, &block); end
+
+  sig { params(object: T.untyped).returns(T::Array[T.untyped]) }
+  def self.wrap(object); end
+
+  sig { returns(T.untyped) }
+  def extract!; end
+
+  sig { returns(ActiveSupport::ArrayInquirer) }
+  def inquiry; end
+end