rspec-junklet 1.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZWQwYjZkZmNlNjlkNmM0MTE2YTMyNzBmYTEwMjU0MThjMjNlYzUzMA==
+  data.tar.gz: !binary |-
+    MjQwNmUwNzQxYTljYWQ1NjhiMTgxNzU0NTk0NzNjNTk4MDhkYjdkNg==
+SHA512:
+  metadata.gz: !binary |-
+    ZTFlNmUzYTRhNzgzNjQyNjViZjA4YWNmYzI5Mjk4NWQ3N2VmNDhkYjZmNzIx
+    NmM5MWE5MDkzNzk1Y2E2YmM2MTEyM2U2YWI0YTU4NjVkOTA1MTdiYjNhZGFj
+    MThhZjU2MWY2ZDRhYTI2ODQ4MTI2YzJkZmM1NTM0ODJiM2Q1YmQ=
+  data.tar.gz: !binary |-
+    OWY2NjNiNmY2ZDM1NTVlNWNmODNmZDIxMGNjODI1N2Y2M2MzMmJkOWY4Nzc4
+    NDY1NTFjZmFjZjU1NjA2YmJiZWI3NzUyYzQ0ZjZmZjYxNjIxYmJlMThkM2Y5
+    OTYyMjA0ZjEwMTk5MGU1ZmQ2N2UxYWZjMmVlYjQyZWEyZWM4NDQ=

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p551

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in junklet.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    rspec-junklet (1.0.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    builder (3.2.2)
+    coderay (1.1.0)
+    cucumber (1.3.18)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.12)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.1.1)
+    diff-lcs (1.2.5)
+    gherkin (2.12.2)
+      multi_json (~> 1.3)
+    method_source (0.8.2)
+    multi_json (1.10.1)
+    multi_test (0.1.1)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.4.2)
+    rspec (2.99.0)
+      rspec-core (~> 2.99.0)
+      rspec-expectations (~> 2.99.0)
+      rspec-mocks (~> 2.99.0)
+    rspec-core (2.99.2)
+    rspec-expectations (2.99.2)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.99.2)
+    slop (3.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  cucumber
+  pry
+  rake (~> 10.0)
+  rspec (~> 2.0)
+  rspec-junklet!

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 CoverMyMeds
+
+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,314 @@
+# Junklet
+
+Cache tiny chunks of unique junk data in RSpec with `junklet :name`; get handy
+clumps of junk data at any time with `junk`. Size your junk with e.g. `junk 100`
+or `junk 4`.
+
+Junklet data is fixture data that:
+
+* We essentially don't care about,
+* But we might want to test for equality somewhere later,
+* And we might need to be unique between runs in case a spec crashes and
+SQLServer fails to clean up the test database
+
+So,
+
+* We want it to be easy to create junk data fields quickly and easily, and
+* If equality fails we want to be led to the offending field by the error
+  message and not just the line number in the stack trace.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rspec-junklet'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rspec-junklet
+
+# Usage
+
+junklet adds two keywords to RSpec's DSL: `junklet`, which defines a `let`
+statement containing junk data, and `junk`, which is a method that returns many
+and varied types of junk data. The former is meant to be used as part of the DSL
+to declare pieces of data to be junk, while the latter is intended to be used
+anywhere inside RSpec to supply the junk data itself.
+
+To illustrate, these statements are functionally identical:
+
+```ruby
+junklet :pigtruck
+let(:pigtruck) { junk }
+```
+
+## Junklet
+
+`junklet` declares a memoized variable containing random junk.
+
+    junklet :var [, :var_2 [...]] [, options_hash]
+
+So, for example,
+
+    junklet :first_name
+
+Creates a `let :first_name` with the value of
+`first_name-774030d0f58d4f588c5edddbdc7f9580` (the hex number is a uuid without
+hyphens and will change with each test _case_, not just each test run).
+
+Currently the options hash only gives you control over the variable names appear
+in the junk data, not the junk data itself. For example,
+
+```ruby
+junklet :host_name, separator: '-'
+```
+
+Creates a `let :host_name`, but changes underscores to hyphens in the string
+value, e.g. `host-name-774030d0f58d4f588c5edddbdc7f9580`. Useful specifically
+for host names, which cannot have underscores in them.
+
+```ruby
+junklet :a_a, :b_b, :c_c, separator: '.'
+```
+
+Does what it says on the tin: creates 3 items with string values of
+`a.a.774...`, `b.b.1234...`, and `c.c.234abc...` respectively. I don't know why
+you'd need this, but hey, if you do there it is.
+
+## Junk
+
+`junk` returns random junk, which can be finely tuned and fiddled with.
+
+```ruby
+junk
+junk (integer|symbol|enumerable|proc) [options]
+```
+
+By default, just calling `junk` from inside a spec or let block returns a random
+hex string 32 bytes long.
+
+### integer
+
+Give junk an integer argument and it will return that many hexadecimal digits of
+junk data. Note that this is HALF the number of digits returned if you were to
+call `SecureRandom.hex(n)`, because `hex(n)` returns n _bytes_, each of which
+requires two hex digits to represent. Since we're more concerned about specific
+byte lengths, `junk(n)` gives you n digits, not n*2 digits representing n bytes.
+
+
+```ruby
+junk 17 - return 17 bytes of junk data
+```
+
+### symbol
+
+junk may be given a symbol denoting the type of data to be returned. Currently
+`:int` and `:bool` are the only supported types. `junk :bool` merely returns
+true or false; `junk :int` is much more complicated and interesting.
+
+```ruby
+junk :bool # Boring. Well, 50% chance of boring.
+```
+
+`junk :int` is the most complicated and/or interesting type of junk. It returns
+a random decimal number, and it has the most options such as `size` (number of
+digits), and `min` and `max` (which sort of do what you'd expect).
+
+By default, `junk :int` returns a random number from 0 to the largest possible
+`Fixnum`, which is 2**62-1.
+
+```ruby
+junk :int # return a random integer from 0 to 2**62-1 (maximum size of
+a Fixnum)
+```
+
+`size`, `min` and `max` control the size and bounds of the random number.
+
+```ruby
+junk :int, size: 3 # returns a 3-digit decimal from 100 to 999.
+junk :int, max: 10 # returns a random number from 0 to 10.
+junk :int, min: 100 # returns a random number from 100 to 2**62-1.
+```
+
+Note: You can mix size with min or max, but they can only be used to further
+restrict the range, not expand it, because that would change the size
+constraint. So these examples work the way you'd expect:
+
+```ruby
+junk :int, size: 4, min: 2000 # random number 2000-9999
+junk :int, size: 4, max: 2000 # random number 1000-2000
+```
+
+But in these examples, `min` and `max` have no effect:
+
+```ruby
+junk :int, size: 2, min: 0 # nope, still gonna get 10-99
+junk :int, size: 2, max: 200 # nope, still gonna get 10-99
+```
+
+Technically, you CAN use BOTH `min` and `max` with `size` to constrain both
+bounds of the number, but this effectively makes the `size` option redundant. It
+will work correctly, but if you remove the size constraint you'll still get the
+same exact range:
+
+```ruby
+# Don't do this - size argument is redundant
+junk :int, size: 3, min: 125, max: 440 # 125-440. size is now redundant.
+```
+
+### Array / Enumerable
+
+If you give junk an `Array`, `Range`, or any other object that implements
+`Enumerable`, it will select an element at random from the collection.
+
+```ruby
+junk [1,3,5,7,9] # pick a 1-digit odd number
+junk (1..5).map {|x| x*2-1 } # pick a 1-digit odd number while trying way too hard
+junk (1..9).step(2) # pick a 1-digit odd number, but now I'm just showing off
+```
+
+*IMPORTANT CAVEAT*: the Enumerable forms all use `.to_a.sample` to get the
+random value, and `.to_a` will cheerfully exhaust all the memory Ruby has if you
+use it on a sufficiently large array.
+
+*LESS-IMPORTANT CAVEAT*: Technically anything that can be converted to an array
+ and then sampled can go through here, so `words.split` would do what you want,
+ but remember that hashes get turned into an array of _pairs_, so expect this
+ weirdness if you ask for it:
+
+```ruby
+junk({a: 42, b: 13}) # either [:a, 42] or [:b, 13]
+```
+
+### Proc
+
+When all else fails, it's time to haul out the lambdas, amirite? The first
+argument ot `junk` can be a proc that yields the desired random value. Let's get
+those odd numbers again:
+
+```ruby
+junk ->{ rand(5)*2 + 1 } # 1-digit odd number
+```
+
+### Other Options
+
+### Exclude
+
+Besides the options that `:int` will take, all of the types will accept an
+`exclude` argument. This is useful if you want to generate more than one piece
+of junk data and ensure that they are different. The exclude option can be given
+a single element, an array, or an enumerable, and if all that fails you can give
+it a proc that accepts the generated value and returns true if the value should
+be excluded. Let's use all these excludes to generate odd numbers again:
+
+```ruby
+junk :int, min: 1, max: 3, exclude: 2 # stupid, but it works
+junk (1..9), exclude: [2,4,6,8]
+junk (1..9), exclude: (2..8) # okay, only returns 1 or 9 but hey,
+                             # they're both odd
+junk :int, exclude: ->(x) { x % 2 == 0 } # reject even numbers
+```
+
+But again, the real advantage is being able to avoid collisions:
+
+```ruby
+let(:id1) { junk (0..9) }
+let(:id2) { junk (0..9), exclude: id1 }
+let(:id3) { junk (0..9), exclude: [id1, id2] }
+
+let(:coinflip) { junk :bool }
+let(:otherside) { junk :bool, exclude: coinflip } # Look I never said
+    # all of these were great ideas, I'm just saying you can DO them.
+```
+
+*VERY IMPORTANT CAVEAT* If you exclude all of the possibilities from the random
+key space, junk will cheerfully go into an infinite loop.
+
+### Format
+
+Formats are here, but need documentating! For now: `format: :int` will cast your
+junk to an integer by calling `.to_i` on it. Other formats include:
+
+* `format: :int` calls `.to_i` on the junk before returning it
+* `format: :string` calls `.to_s` on the junk
+* `format: "%s"` (or any other string) calls sprintf on the junk with the
+  string as the format string
+* `format: SomeClass` passes the junk to `SomeClass.new`, returning an instance
+  of `SomeClass`. *Note:* If you plan on combining this with `exclude`, make
+  sure your class implements the `==` operator.
+* `format: ->(x) { ... }` passes the junk to your Proc
+
+# TODO
+
+* Allow all args to junk to be passed to junklet. Use explicit `type` option to
+  specify the type. E.g. `junklet :foo, :bar, :baz, type: :int, max: 14,
+  exclude: [:qaz, :qux]`. _(Do we want to allow a flag for mutually exclusive?)_
+
+# Background
+
+At CoverMyMeds we have a legacy impingement that prevents us sometimes from
+clearing out data from previous test runs. As a result we often have required
+fields in tests that must be unique but are tested elsewhere, so we don't really
+care about them in the current test run. For the current test we just want to
+stub out that field with something unique but we also want to communicate to the
+developer that the contents of the field are not what we currently care about.
+
+Currently we do this with `SecureRandom.uuid`, so we'll see code like
+this frequently in RSpec:
+
+```ruby
+let(:first_name) { SecureRandom.uuid }
+let(:last_name) { SecureRandom.uuid }
+let(:address) { SecureRandom.uuid }
+let(:city) { SecureRandom.uuid }
+let(:state) { SecureRandom.uuid }
+let(:phone) { SecureRandom.uuid }
+```
+
+...etc. Later in the spec we'll often test against those stubs, e.g. with
+`expect(user.first_name).to eq(first_name)` but this idiom expresses that we
+only care about the equality, not the actual contents.
+
+Junklet seeks to improve the readability and conciseness of this intention. One
+thing that bugs me about the above approach is that if a weird regression bug
+appears and an unimportant field is the source of a crash. So with Junklet I
+also wanted to add the ability to call out the offending field by name. In
+theory we could just write `let(:first_name) { 'first_name-' + SecureRandom.uuid
+}` but in practice that creates duplication in the code and muddies the original
+idiom of "uncared-about" data.
+
+Enter Junklet:
+
+```ruby
+junklet :first_name
+junklet :last_name
+junklet :address
+junklet :city
+junklet :state
+junklet :phone
+```
+
+Or, if you don't want the junklets to sprawl vertically,
+
+```ruby
+junklet :first_name, :last_name, :address, :city, :state, :phone
+```
+
+This will have the same effect as calling `let` on the named fields and setting
+the fieldname and a 32-byte hex string (a uuid with hyphens removed) to be the
+memoized value.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/junklet/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Write specs to document how your change is to be used
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request

data/lib/junklet/junk.rb

@@ -0,0 +1,118 @@
+module Junklet
+  module Junk
+    def junk(*args)
+      # TODO: It's long past time to extract this....
+
+      # args.first can be
+      # - an integer indicating the size of the hex string to return
+      # - a symbol denoting the base type, e.g. :int
+      # - an array to sample from
+      # - a range or Enumerable to sample from. WARNING: will call
+      #   .to_a on it first, which might be expensive
+      # - a generator Proc which, when called, will generate the
+      #   value to use.
+      #
+      # args.rest is a hash of options:
+      # - sequence: Proc or Array of values to choose from.
+      # - exclude: value, array of values, or proc to exclude. If a
+      #   Proc is given, it takes the value generated and returns
+      #   true if the value should be excluded.
+      #
+      # - for int:
+      #   - min: minimum number to return. Default: 0
+      #   - max: upper limit of range
+      #   - exclude: number, array of numbers, or proc to
+      #     exclude. If Proc is provided, tests the number against
+      #     the Proc an excludes it if the Proc returns true. This
+      #     is implemented except for the proc.
+
+      # FIXME: Raise Argument error unless *args.size is 0-2
+      # FIXME: If arg 1 is a hash, it's the options hash, raise
+      #        ArgumentError unless args.size == 1
+      # FIXME: If arg 2 present, Raise Argument error unless it's a
+      #        hash.
+      # FIXME: Figure out what our valid options are and parse them;
+      #        raise errors if present.
+
+      junk_types = [Symbol, Array, Enumerable, Proc]
+      if args.size > 0 && junk_types.any? {|klass| args.first.is_a?(klass) }
+        type = args.shift
+        opts = args.last || {}
+
+        excluder = if opts[:exclude]
+                     if opts[:exclude].is_a?(Proc)
+                       opts[:exclude]
+                     else
+                       ->(x) { Array(opts[:exclude]).include?(x) }
+                     end
+                   else
+                     ->(x) { false }
+                   end
+
+        formatter = case opts[:format]
+                    when :string
+                      ->(x) { x.to_s }
+                    when :int
+                      ->(x) { x.to_i }
+                    when String
+                      ->(x) { sprintf(opts[:format], x) }
+                    when Class
+                      ->(x) { opts[:format].new(x) }
+                    when Proc
+                      opts[:format]
+                    else
+                      ->(x) { x }
+                    end
+
+        # TODO: Refactor me. Seriously, this is a functional
+        # programming version of the strategy pattern. Wouldn't it
+        # be neat if we had some kind of object-oriented language
+        # available here?
+        case type
+        when :int
+          # min,max cooperate with size to further constrain it. So
+          # size: 2, min: 30 would be min 30, max 99.
+          if opts[:size]
+            sized_min = 10**(opts[:size]-1)
+            sized_max = 10**opts[:size]-1
+          end
+          explicit_min = opts[:min] || 0
+          explicit_max = (opts[:max] || 2**62-2) + 1
+
+          if sized_min
+            min = [sized_min, explicit_min].max
+            max = [sized_max, explicit_max].min
+          else
+            min = sized_min || explicit_min
+            max = sized_max || explicit_max
+          end
+
+          min,max = max,min if min>max
+
+          generator = -> { rand(max-min) + min }
+        when :bool
+          generator = -> { [true, false].sample }
+        when Array, Enumerable
+          generator = -> { type.to_a.sample }
+        when Proc
+          generator = type
+        else
+          raise "Unrecognized junk type: '#{type}'"
+        end
+
+        begin
+          val = formatter.call(generator.call)
+        end while excluder.call(val)
+        val
+      else
+        size = args.first.is_a?(Numeric) ? args.first : 32
+        # hex returns size*2 digits, because it returns a 0..255 byte
+        # as a hex pair. But when we want junt, we want *bytes* of
+        # junk. Get (size+1)/2 chars, which will be correct for even
+        # sizes and 1 char too many for odds, so trim off with
+        # [0...size] (note three .'s to trim off final char)
+        SecureRandom.hex((size+1)/2)[0...size]
+      end
+    end
+  end
+end

data/lib/junklet/junklet.rb

@@ -0,0 +1,25 @@
+module Junklet
+  module Junklet
+    def junklet(*args)
+      # TODO: figure out how to use this to wrap junk in junklet,
+      # so that junklet can basically have all the same options as
+      # junk does. E.g. junklet :ddid, :pcn, :group, type: :int,
+      # min: 100000, max: 999999, etc, and you'd get back 3
+      # junklets of 6-digit numbers.
+      opts = args.size > 1 && !args.last.is_a?(Symbol) && args.pop || {}
+
+      names = args.map(&:to_s)
+
+      separator = opts[:separator] || '_'
+      names = names.map {|name| name.gsub(/_/, separator)}
+
+      args.zip(names).each do |arg, name|
+        make_junklet arg, name, separator, junk
+      end
+    end
+
+    def make_junklet(let_name, name, separator, junk_data)
+      let(let_name) { "#{name}#{separator}#{junk_data}" }
+    end
+  end
+end

data/lib/junklet/version.rb

@@ -0,0 +1,3 @@
+module Junklet
+  VERSION = "1.1.0"
+end

data/lib/junklet.rb

@@ -0,0 +1,9 @@
+require "junklet/version"
+require "junklet/junk"
+require "junklet/junklet"
+
+RSpec.configure do |config|
+  config.extend(Junklet::Junklet)
+  config.extend(Junklet::Junk) # when metaprogramming cases, you may need junk in ExampleGroups
+  config.include(Junklet::Junk)
+end

data/lib/line.rb

@@ -0,0 +1,44 @@
+class Line < String
+  def initialize(line="")
+    super
+  end
+
+  def indent
+    ' ' * (size - lstrip.size)
+  end
+
+  def let?
+    match(/^\s*let\s*\(/) && !junklet?
+  end
+
+  def junklet?
+     already_junklet? || secure_random?
+  end
+
+  def already_junklet?
+    match(/^\s*junklet\b/)
+  end
+
+  def secure_random?
+    match(/^\s*(let)\s*\(?([^)]*)\)\s*{\s*SecureRandom.(uuid|hex)\s*}/)
+  end
+
+  def code?
+    empty? || (!let? && !junklet?)
+  end
+
+  def names
+    return nil unless let? || junklet?
+    match(/^\s*(let|junklet)\s*\(?([^)]*)\)?/) \
+      .captures[1..-1] \
+      .join('') \
+      .split(/,/) \
+      .map(&:strip)
+  end
+
+  def convert
+    return nil unless junklet?
+    return self if already_junklet?
+    Line.new("#{indent}junklet #{names.first}")
+  end
+end

data/rspec-junklet.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'junklet/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec-junklet"
+  spec.version       = Junklet::VERSION
+  spec.authors       = ["David Brady"]
+  spec.email         = ["dbrady@shinybit.com"]
+  spec.summary       = "Easily create junk data for specs"
+  spec.description   = "Works like let for rspec, but creates unique random junk data"
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 2.0"
+  spec.add_development_dependency "cucumber"
+  spec.add_development_dependency "pry"
+end

data/spec/fixtures/block1_after.txt

@@ -0,0 +1,6 @@
+    let(:name) { "Bob" }
+    let(:city) { "Faketown" }
+    let(:extra) { true }
+    let(:pants) { ON_FIRE }
+
+    junklet :address, :state, :zip

data/spec/fixtures/block1_before.txt

@@ -0,0 +1,7 @@
+    let(:name) { "Bob" }
+    junklet :address
+    let(:city) { "Faketown" }
+    junklet :state
+    junklet :zip
+    let(:extra) { true }
+    let(:pants) { ON_FIRE }