hypothesis-specs 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ca2e609a02788991ddea6552d8dde5660b918308
+  data.tar.gz: f0c02fb905b411d91a55fece2d5e5117a130d984
+SHA512:
+  metadata.gz: 7d3750c2b0a756f38ec82525157b8471d1dab93c0bcf139260da68b37a57d8d9fea3bb8faf9ef947c36534dbb51658563e3d4ff1714e9f9617ac98d6a516b5a2
+  data.tar.gz: 732da786e9e63999fd709338edfae86466b807288a787e8f8e0cfed8b667c911eef15424611b2f8c3990fc95f1cf6d97a6ea3a7b45f1c04ce603e128cc4e56ea

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## Hypothesis for Ruby 0.0.3 (2018-02-19)
+
+This is an initial developer preview of Hypothesis for Ruby.
+It's ready to use, but isn't yet stable and has significant
+limitations. It is mostly released so that people can easily give
+feedback on the API and implementation, and is likely to change
+substantially before a stable release.
+
+Note that while there were some earlier release numbers internally,
+these were pulled. This is the first official release.

data/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "hypothesis-ruby-core"
+version = "0.1.0"
+authors = ["David R. MacIver <david@drmaciver.com>"]
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+helix = '0.7.2'
+rand = '0.3'

data/LICENSE.txt

@@ -0,0 +1,8 @@
+Copyright (c) 2018, David R. MacIver
+
+All code in this repository except where explicitly noted otherwise is released
+under the Mozilla Public License v 2.0. You can obtain a copy at http://mozilla.org/MPL/2.0/.
+
+Some code in this repository may come from other projects. Where applicable, the
+original copyright and license are noted and any modifications made are released
+dual licensed with the original license.

data/README.markdown

@@ -0,0 +1,86 @@
+# Hypothesis for Ruby
+
+Hypothesis is a powerful, flexible, and easy to use library for *property-based testing*.
+
+In property-based testing,
+in contrast to traditional *example-based testing*,
+a test is written not against a single example but as a statement that should hold for any of a range of possible values.
+
+## Usage
+
+In Hypothesis for Ruby, a test looks something like this:
+
+```ruby
+require "hypothesis"
+
+RSpec.configure do |config|
+  config.include(Hypothesis)
+  config.include(Hypothesis::Possibilities)
+end
+
+RSpec.describe "removing an element from a list" do
+  it "results in the element no longer being in the list" do
+    hypothesis do
+      # Or lists(of: integers, min_size: 1), but this lets us
+      # demonstrate assume.
+      values = any array(of: integers)
+
+      # If this is not true then the test will stop here.
+      assume values.size > 0
+
+      to_remove = any element_of(values)
+
+      values.delete_at(values.index(to_remove))
+
+      # Will fail if the value ws duplicated in the list.
+      expect(values.include?(to_remove)).to be false
+      
+    end
+  end
+end
+```
+
+This would then fail with:
+
+```
+  1) removing an element from a list results in the element no longer being in the list
+     Failure/Error: expect(values.include?(to_remove)).to be false
+
+       Given #1: [0, 0]
+       Given #2: 0
+
+       expected false
+            got true
+```
+
+The use of RSpec here is incidental:
+Hypothesis for Ruby works just as well with minitest,
+and should work with anything else you care to use.
+
+## Getting Started
+
+Hypothesis is not available on rubygems.org as a developer preview.
+If you want to try it today you can use the current development branch by adding the following to your Gemfile:
+
+```ruby
+gem 'hypothesis-specs'
+```
+
+The API is still in flux, so be warned that you should expect it to break on upgrades!
+Right now this is really more to allow you to try it out and provide feedback than something you should expect to rely on.
+The more feedback we get, the sooner it will get here!
+
+Note that in order to use Hypothesis for Ruby, you will need a rust toolchain installed.
+Please go to [https://www.rustup.rs](https://www.rustup.rs) and follow the instructions if you do not already have one.
+
+## Project Status
+
+Hypothesis for Ruby is currently in an *early alpha* stage.
+It works, and has a solid core set of features, but you should expect to find rough edges,
+it is far from feature complete, and the API makes no promises of backwards compatibility.
+
+Right now you should consider it to be more in the spirit of a developer preview.
+You can and should try it out, and hopefully you will find all sorts of interesting bugs in your code by doing so!
+But you'll probably find interesting bugs in Hypothesis too,
+and we'd appreciate you reporting them,
+as well as any just general usability issues or points of confusion you have.

data/Rakefile

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'helix_runtime/build_task'
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+
+  require 'rake/testtask'
+
+  Rake::TestTask.new(minitests: :build) do |t|
+    t.test_files = FileList['minitests/**/test_*.rb']
+    t.verbose = true
+  end
+
+  task test: %i[build spec minitests]
+rescue LoadError
+end
+
+# Monkeypatch build to fail on error.
+# See https://github.com/tildeio/helix/issues/133
+module HelixRuntime
+  class Project
+    alias original_build cargo_build
+
+    def cargo_build
+      raise 'Build failed' unless original_build
+    end
+  end
+end
+
+HelixRuntime::BuildTask.new
+
+task :format do
+  sh 'bundle exec rubocop -a lib spec minitests ' \
+  'Rakefile hypothesis-specs.gemspec'
+end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new(:runyard) do |t|
+    t.files = [
+      'lib/hypothesis.rb', 'lib/hypothesis/errors.rb',
+      'lib/hypothesis/possible.rb'
+    ]
+    t.options = ['--markup=markdown', '--no-private']
+  end
+
+  task doc: :runyard do
+    YARD::Registry.load
+
+    objs = YARD::Registry.select do |o|
+      is_private = false
+      t = o
+      until t.root?
+        if t.visibility != :public
+          is_private = true
+          break
+        end
+        t = t.parent
+      end
+
+      !is_private && o.docstring.blank?
+    end
+
+    objs.sort_by! { |o| o.name.to_s }
+
+    unless objs.empty?
+      abort "Undocumented objects: #{objs.map(&:name).join(', ')}"
+    end
+  end
+rescue LoadError
+end
+
+task :gem do
+  uncommitted = `git ls-files lib/ --others --exclude-standard`.split
+  uncommitted_ruby = uncommitted.grep(/\.rb$/)
+  uncommitted_ruby.sort!
+  unless uncommitted_ruby.empty?
+    abort 'Cannot build gem with uncomitted Ruby '\
+      "files #{uncommitted_ruby.join(', ')}"
+  end
+
+  sh 'rm -rf hypothesis-specs*.gem'
+  sh 'git clean -fdx lib'
+  sh 'gem build hypothesis-specs.gemspec'
+end
+
+def git(*args)
+  sh 'git', *args
+end
+
+file 'secrets.tar.enc' => 'secrets' do
+  sh 'rm -f secrets.tar secrets.tar.enc'
+  sh 'tar -cf secrets.tar secrets'
+  sh 'travis encrypt-file secrets.tar'
+end
+
+task deploy: :gem do
+  on_master = system("git merge-base  --is-ancestor HEAD origin/master")
+
+  unless on_master
+    puts 'Not on master, so no deploy'
+    next
+  end
+
+  spec = Gem::Specification.load('hypothesis-specs.gemspec')
+
+  succeeded = system('git', 'tag', spec.version.to_s)
+
+  unless succeeded
+    puts "Looks like we've already done this release."
+    next
+  end
+
+  unless File.directory? 'secrets'
+    sh 'rm -rf secrets'
+    sh 'openssl aes-256-cbc -K $encrypted_b0055249143b_key -iv ' \
+    '$encrypted_b0055249143b_iv -in secrets.tar.enc -out secrets.tar -d'
+
+    sh 'tar -xvf secrets.tar'
+  end
+
+  git('config', 'user.name', 'Travis CI on behalf of David R. MacIver')
+  git('config', 'user.email', 'david@drmaciver.com')
+  git('config', 'core.sshCommand', 'ssh -i secrets/deploy_key')
+  git(
+    'remote', 'add', 'ssh-origin',
+    'git@github.com:HypothesisWorks/hypothesis-ruby.git'
+  )
+
+  sh(
+    'ssh-agent', 'sh', '-c',
+    'chmod 0600 secrets/deploy_key && ssh-add secrets/deploy_key && ' \
+    'git push ssh-origin --tags'
+  )
+
+  sh 'rm -f ~/.gem/credentials'
+  sh 'mkdir -p ~/.gem'
+  sh 'ln -s $(pwd)/secrets/api_key.yaml ~/.gem/credentials'
+  sh 'chmod 0600 ~/.gem/credentials'
+  sh 'gem push hypothesis-specs*.gem'
+end

data/ext/Makefile

@@ -0,0 +1,7 @@
+all:
+	cd ..
+	rake build
+clean:
+	rm -rf ../target
+
+install: ;

data/ext/extconf.rb

@@ -0,0 +1,5 @@
+if !system('cargo --version')
+  raise 'Hypothesis requires cargo to be installed (https://www.rust-lang.org/)'
+end
+
+require 'rake'

data/lib/hypothesis.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'hypothesis/errors'
+require 'hypothesis/possible'
+require 'hypothesis/testcase'
+require 'hypothesis/engine'
+require 'hypothesis/world'
+
+# This is the main module for using Hypothesis.
+# It is expected that you will include this in your
+# tests, but its methods are also available on the
+# module itself.
+#
+# The main entry point for using this is the
+# {Hypothesis#hypothesis} method. All of the other
+# methods make sense only inside blocks passed to
+# it.
+module Hypothesis
+  # @!visibility private
+  HYPOTHESIS_LOCATION = File.dirname(__FILE__)
+
+  # @!visibility private
+  def hypothesis_stable_identifier
+    # Attempt to get a "stable identifier" for any any
+    # call into hypothesis. We use these to create
+    # database keys (or will when we have a database) that
+    # are stable across runs, so that when a test that
+    # previously failed is rerun, we can fetch and reuse
+    # the previous examples.
+
+    # Note that essentially any answer to this method is
+    # "fine" in that the failure mode is that sometiems we
+    # just won't run the same test, but it's nice to keep
+    # this as stable as possible if the code isn't changing.
+
+    # Minitest makes it nice and easy to create a stable
+    # test identifier, because it follows the classic xunit
+    # pattern where a test is just a method invocation on a
+    # fresh test class instance and it's easy to find out
+    # which invocation that was.
+    return "#{self.class.name}::#{@NAME}" if defined? @NAME
+
+    # If we are running in an rspec example then, sadly,
+    # rspec take the entirely unreasonable stance that
+    # the correct way to pass data to a test is by passing
+    # it as a function argument. Honestly, what is this,
+    # Haskell? Ahem. Perfectly reasonable design decisions
+    # on rspec's part, this creates some annoying difficulties
+    # for us. We solve this through brute force and ignorance
+    # by relying on the information we want being in the
+    # inspect for the Example object, even if it's just there
+    # as a string.
+    begin
+      is_rspec = is_a? RSpec::Core::ExampleGroup
+      # We do our coverage testing inside rspec, so this will
+      # never trigger! Though we also don't currently have a
+      # test that covers it outside of rspec...
+      # :nocov:
+    rescue NameError
+      is_rspec = false
+    end
+    # :nocov:
+
+    if is_rspec
+      return [
+        self.class.description,
+        inspect.match(/"([^"]+)"/)[1]
+      ].join(' ')
+    end
+
+    # Fallback time! We just walk the stack until we find the
+    # entry point into code we control. This will typically be
+    # where "hypothesis" was called.
+    Thread.current.backtrace.each do |line|
+      return line unless line.include?(Hypothesis::HYPOTHESIS_LOCATION)
+    end
+    # This should never happen unless something very strange is
+    # going on.
+    # :nocov:
+    raise 'BUG: Somehow we have no caller!'
+    # :nocov:
+  end
+
+  # Run a test using Hypothesis.
+  #
+  # For example:
+  #
+  # ```ruby
+  # hypothesis do
+  #   x = any integer
+  #   y = any integer(min: x)
+  #   expect(y).to be >= x
+  # end
+  # ```
+  #
+  # The arguments to `any` are `Possible` instances which
+  # specify the range of value values for it to return.
+  #
+  # Typically you would include this inside some test in your
+  # normal testing framework - e.g. in an rspec it block or a
+  # minitest test method.
+  #
+  # This will run the block many times with integer values for
+  # x and y, and each time it will pass because we specified that
+  # y had a minimum value of x.
+  # If we changed it to `expect(y).to be > x` we would see output
+  # like the following:
+  #
+  # ```
+  # Failure/Error: expect(y).to be > x
+  #
+  # Given #1: 0
+  # Given #2: 0
+  # expected: > 0
+  #      got:   0
+  # ```
+  #
+  # In more detail:
+  #
+  # hypothesis calls its provided block many times. Each invocation
+  # of the block is a *test case*.
+  # A test case has three important features:
+  #
+  # * *givens* are the result of a call to self.given, and are the
+  #   values that make up the test case. These might be values such
+  #   as strings, integers, etc. or they might be values specific to
+  #   your application such as a User object.
+  # * *assumptions*, where you call `self.assume(some_condition)`. If
+  #   an assumption fails (`some_condition` is false), then the test
+  #   case is considered invalid, and is discarded.
+  # * *assertions* are anything that will raise an error if the test
+  #   case should be considered a failure. These could be e.g. RSpec
+  #   expectations or minitest matchers, but anything that throws an
+  #   exception will be treated as a failed assertion.
+  #
+  # A test case which satisfies all of its assumptions and assertions
+  # is *valid*. A test-case which satisfies all of its assumptions but
+  # fails one of its assertions is *failing*.
+  #
+  # A call to hypothesis does the following:
+  #
+  # 1. It tries to *generate* a failing test case.
+  # 2. If it succeeded then it will *shrink* that failing test case.
+  # 3. Finally, it will *display* the shrunk failing test case by
+  #    the error from its failing assertion, modified to show the
+  #    givens of the test case.
+  #
+  # Generation consists of randomly trying test cases until one of
+  # three things has happened:
+  #
+  # 1. It has found a failing test case. At this point it will start
+  #    *shrinking* the test case (see below).
+  # 2. It has found enough valid test cases. At this point it will
+  #    silently stop.
+  # 3. It has found so many invalid test cases that it seems unlikely
+  #    that it will find any more valid ones in a reasonable amount of
+  #    time. At this point it will either silently stop or raise
+  #    `Hypothesis::Unsatisfiable` depending on how many valid
+  #    examples it found.
+  #
+  # *Shrinking* is when Hypothesis takes a failing test case and tries
+  # to make it easier to understand. It does this by replacing the givens
+  # in the test case with smaller and simpler values. These givens will
+  # still come from the possible values, and will obey all the usual
+  # constraints.
+  # In general, shrinking is automatic and you shouldn't need to care
+  # about the details of it. If the test case you're shown at the end
+  # is messy or needlessly large, please file a bug explaining the problem!
+  #
+  # @param max_valid_test_cases [Integer] The maximum number of valid test
+  #   cases to run without finding a failing test case before stopping.
+  def hypothesis(max_valid_test_cases: 200, &block)
+    unless World.current_engine.nil?
+      raise UsageError, 'Cannot nest hypothesis calls'
+    end
+    begin
+      World.current_engine = Engine.new(
+        max_examples: max_valid_test_cases
+      )
+      World.current_engine.run(&block)
+    ensure
+      World.current_engine = nil
+    end
+  end
+
+  # Supplies a value to be used in your hypothesis.
+  # @note It is invalid to call this method outside of a hypothesis block.
+  # @return [Object] A value provided by the possible argument.
+  # @param possible [Possible] A possible that specifies the possible values
+  #   to return.
+  # @param name [String, nil] An optional name to show next to the result on
+  #   failure. This can be helpful if you have a lot of givens in your
+  #   hypothesis, as it makes it easier to keep track of which is which.
+  def any(possible, name: nil, &block)
+    if World.current_engine.nil?
+      raise UsageError, 'Cannot call any outside of a hypothesis block'
+    end
+
+    World.current_engine.current_source.any(
+      possible, name: name, &block
+    )
+  end
+
+  # Specify an assumption of your test case. Only test cases which satisfy
+  # their assumptions will treated as valid, and all others will be
+  # discarded.
+  # @note It is invalid to call this method outside of a hypothesis block.
+  # @note Try to use this only with "easy" conditions. If the condition is
+  #   too hard to satisfy this can make your testing much worse, because
+  #   Hypothesis will have to retry the test many times and will struggle
+  #   to find "interesting" test cases. For example `assume(x != y)` is
+  #   typically fine, and `assume(x == y)` is rarely a good idea.
+  # @param condition [Boolean] The condition to assume. If this is false,
+  #   the current test case will be treated as invalid and the block will
+  #   exit by throwing an exception. The next test case will then be run
+  #   as normal.
+  def assume(condition)
+    if World.current_engine.nil?
+      raise UsageError, 'Cannot call assume outside of a hypothesis block'
+    end
+    World.current_engine.current_source.assume(condition)
+  end
+end