pork 0.9.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3a3d84ef0bd9962c3d48dad6baf8182cdea451d3
-  data.tar.gz: 65e166bbe7e9fe9fcc91f9b8a66c4457a9a97c37
+  metadata.gz: d8259f46bbdff005a8f03f13a6106bcd7a264df4
+  data.tar.gz: e515132bb2458ddec395e4d50971cd16f7821cb5
 SHA512:
-  metadata.gz: 406eace0873f1bbf764fd77a041df9e92368eb82c3681ac5b99a9bd999ed508e71412f2552b04cd8129eb67eb8efbc9fe8db5f900c12bc4ede8d4b7848c2caf0
-  data.tar.gz: 4a57b245e51c6132d7d5e9ba3e4bdca5e7741b06830da52289fefcc05e70e7d0d80091c852893891a604f9097a39a9906539cabdaf28edcb98b0c36bb9791bf5
+  metadata.gz: 334364aaa0941b31830ce6998eff0c2715376cd74cf9befcdeeb79d1c6344d10b91aa44b66e24ec8b14f3217eb67bcbfd8cc6816685a5b43ed717d69c1d3d9b3
+  data.tar.gz: e5aa86f3e2976666d53b831c58b5bb70831e5e8b08dfaa87fa94b4810cb7acfe7c576ffb0c5281032991c8b652f661312f84a59e30d17a7018991c11f615b727

data/.gitignore

@@ -1 +1,2 @@
 /pkg/
+/coverage/

data/.travis.yml

@@ -1,9 +1,11 @@
 
 language: ruby
 rvm:
+  - 1.9
   - 2.0
   - 2.1
   - rbx-2
   - jruby
 
+install: 'bundle install --retry=3'
 script: 'ruby -r bundler/setup -S rake test'

data/CHANGES.md

@@ -1,5 +1,40 @@
 # CHANGES
 
+## Pork 1.0.0 -- 2014-11-20
+
+### Bugs fixed
+
+* Now exceptions raised in after hook are properly rescued.
+* Previously runtime includes loading time, now it only includes
+  test running time.
+
+### Incompatible changes
+
+* Internal structure was completed rewritten.
+* Simply `require 'pork'` would no longer introduce `Kernel#should`.
+  Use `require 'pork/should'` to bring it back. (`require 'pork/auto'`
+  would already do this for you)
+* Removed `@__pork__desc__` (which is implementation detail anyway)
+* Renamed `Pork.report_at_exit` to `Pork.autorun`
+
+### Enhancement
+
+* `Pork.autorun` also accepts a flag to enable/disable autorun.
+* Introduced `Pork::Expector#expect` to replace `Kernel#should`
+* `Kernel#should` is now optional and a wrapper around `Pork::Expector#expect`
+
+* Introduced `Pork::Inspect#diff_hash`. See README.md for
+  `Pork.inspect_failure_mode` for detail.
+* Introduced `Pork.execute_mode`. See README.md for detail
+* Introduced `Pork::Isolate` which allows you to run a specific test.
+* Introduced `Pork::Shuffle` which we could run tests in random order.
+  See README.md for `Pork.execute_mode` for detail.
+* Introduced `Pork::Parallel` which we could run tests in parallel.
+  See README.md for `Pork.execute_mode` for detail.
+
+* Introduced `Pork::Executor#pork_stat` to access the current stat from test.
+* Introduced mutant integration.
+
 ## Pork 0.9.2 -- 2014-11-07
 
 * Pork::Error is now a StandardError instead of an Exception.

data/Gemfile

@@ -0,0 +1,13 @@
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+
+gem 'simplecov', :require => false if ENV['COV']
+gem 'coveralls', :require => false if ENV['CI']
+
+platform :rbx do
+  gem 'rubysl-singleton' # used in rake
+end

data/README.md

@@ -1,4 +1,4 @@
-# Pork [![Build Status](https://secure.travis-ci.org/godfat/pork.png?branch=master)](http://travis-ci.org/godfat/pork)
+# Pork [![Build Status](https://secure.travis-ci.org/godfat/pork.png?branch=master)](http://travis-ci.org/godfat/pork) [![Coverage Status](https://coveralls.io/repos/godfat/pork/badge.png)](https://coveralls.io/r/godfat/pork)
 
 by Lin Jen-Shin ([godfat](http://godfat.org))
 
@@ -12,7 +12,7 @@ by Lin Jen-Shin ([godfat](http://godfat.org))
 
 Pork -- Simple and clean and modular testing library.
 
-[Bacon][] reimplemented around 250 lines of code.
+Inspired by [Bacon][].
 
 [Bacon]: https://github.com/chneukirchen/bacon
 
@@ -272,6 +272,98 @@ describe Hash do
 end
 ```
 
+## What if I don't want any monkey patches?
+
+For the lazies and the greatest convenience but the least flexibility, we
+could simply `require 'pork/auto'` and everything above should work.
+However, as you can see, there are some monkey patches around, and you
+might not want to see any of them. In this case *DON'T* require it.
+
+Here's what `require 'pork/auto'` would do:
+
+``` ruby
+require 'pork'
+require 'pork/should'
+extend Pork::API
+Pork.autorun
+```
+
+Here it `require 'pork/should'`, and it would load the monkey patches for
+inserting `Kernel#should` shown in SYNOPSIS. This is actually optional,
+and could be replaced with `Pork::Executor#expect`. For example, we could
+also write it this way:
+
+``` ruby
+require 'pork'
+
+Pork::API.describe Array do
+  before do
+    @array = []
+  end
+
+  after do
+    @array.clear
+  end
+
+  would 'be empty' do
+    expect(@array).empty?
+    expect(@array).not.include? 1
+  end
+end
+
+# or: Pork.autorun
+Pork::Executor.execute.report
+```
+
+As you can see, this way we no longer use any monkey patches and we don't
+even use `at_exit` hook to run tests. Also note that we could turn autorun
+off by passing `false` to it:
+
+``` ruby
+Pork.autorun(false)
+```
+
+We might need to turn autorun off occasionally, for example, we do need to
+turn this off when integrating [mutant][]. Passing `true` again to `autorun`
+could re-enable it.
+
+[mutant]: https://github.com/mbj/mutant
+
+## Where's the pork command?
+
+It's not implemented. No strong reasons. You could simply run the tests by
+requiring the files defining tests, or execute them directly, with autorun
+enabled. (by `require 'pork/auto'` or call `Pork.autorun`)
+
+Here's a example command to require all test files and automatically run them.
+With [Fish shell][]:
+
+    ruby -Ilib -rpork/auto -r(ls ./test/test_*.rb) -e ''
+
+Or
+
+    ruby -Ilib -rpork/auto -r(find ./test -name '*.rb' -type f) -e ''
+
+With Bash shell:
+
+    ruby -Ilib -rpork/auto $(ls ./test/test_*.rb | awk '{print "-r" $0}') -e ''
+
+Personally I have a [rake task][gemgem] which would do this for me, so I just
+run `rake test` to run all the tests.
+
+[Fish shell]: http://fishshell.com/
+[gemgem]: https://github.com/godfat/gemgem
+
+## Mutant integration
+
+Pork also ships with [mutant][] integration. Here's an example to run it:
+
+    mutant -Ilib -rjellyfish --use pork Jellyfish
+
+for [jellyfish][].
+
+[jellyfish]: https://github.com/godfat/jellyfish
+
 ## The API
 
 ### Kernel#should
@@ -323,7 +415,7 @@ end
 The assertions would only fail whenever the result was `false` or `nil`,
 otherwise pass.
 
-### Pork::Should#satisfy
+### Pork::Expect#satisfy
 
 If we want to have custom verifier other than the methods from questioning
 object, this is it.
@@ -355,7 +447,7 @@ describe do
 end
 ```
 
-### Pork::Should#not
+### Pork::Expect#not
 
 An easy way to negate the expectation.
 
@@ -365,7 +457,7 @@ require 'pork/auto'
 would{ 1.should.not.eq 2 }
 ```
 
-### Pork::Should#eq
+### Pork::Expect#eq
 
 To avoid warnings from Ruby, using `eq` instead of `==`. It's fine if you
 still prefer using `==` if you don't care about warnings.
@@ -376,7 +468,7 @@ require 'pork/auto'
 would{ 1.should.eq 1 }
 ```
 
-### Pork::Should#lt
+### Pork::Expect#lt
 
 To avoid warnings from Ruby, using `lt` instead of `<`. It's fine if you
 still prefer using `<` if you don't care about warnings.
@@ -387,7 +479,7 @@ require 'pork/auto'
 would{ 1.should.lt 2 }
 ```
 
-### Pork::Should#gt
+### Pork::Expect#gt
 
 To avoid warnings from Ruby, using `gt` instead of `>`. It's fine if you
 still prefer using `>` if you don't care about warnings.
@@ -398,7 +490,7 @@ require 'pork/auto'
 would{ 1.should.gt 0 }
 ```
 
-### Pork::Should#lte
+### Pork::Expect#lte
 
 To avoid warnings from Ruby, using `lte` instead of `<=`. It's fine if you
 still prefer using `<=` if you don't care about warnings.
@@ -409,7 +501,7 @@ require 'pork/auto'
 would{ 1.should.lte 1 }
 ```
 
-### Pork::Should#gte
+### Pork::Expect#gte
 
 To avoid warnings from Ruby, using `gte` instead of `>=`. It's fine if you
 still prefer using `>=` if you don't care about warnings.
@@ -420,7 +512,7 @@ require 'pork/auto'
 would{ 1.should.gte 1 }
 ```
 
-### Pork::Should#raise
+### Pork::Expect#raise
 
 Expect for exceptions! There are two ways to call it. Either you could use
 lambda to wrap the questioning expression, or you could simply pass a block
@@ -429,7 +521,7 @@ as the questioning expression.
 ``` ruby
 require 'pork/auto'
 
-describe 'Pork::Should#raise' do
+describe 'Pork::Expect#raise' do
   would 'check with a block' do
     e = should.raise(RuntimeError){ raise "nnf" }
     e.should.message.include?("nnf")
@@ -442,7 +534,7 @@ describe 'Pork::Should#raise' do
 end
 ```
 
-### Pork::Should#throw
+### Pork::Expect#throw
 
 Expect for something to be thrown. There are two ways to call it. Either
 you could use lambda to wrap the questioning expression, or you could
@@ -495,14 +587,6 @@ a string. The _default_ description is also `:default`.
 Each `would` block would be run inside a new instance of the describing
 `Pork::Executor` to isolate instance variables.
 
-``` ruby
-require 'pork/auto'
-
-would do
-  desc.should.eq :default
-end
-```
-
 ### Pork::API.before
 
 Each `before` block would be called before each `would` block (test case).
@@ -593,6 +677,32 @@ describe do
 end
 ```
 
+### Pork::Executor#expect
+
+It is the core of `Kernel#should`. Think of:
+
+``` ruby
+object.should.eq(1)
+```
+
+is equivalent to:
+
+``` ruby
+expect(object).eq(1)
+```
+
+Also:
+
+``` ruby
+object.should('message').eq(1)
+```
+
+is equivalent to:
+
+``` ruby
+expect(object, 'message').eq(1)
+```
+
 ### Pork::Executor#skip
 
 At times we might want to skip some tests while leave the codes there without
@@ -647,28 +757,43 @@ describe do
 end
 ```
 
-### Pork.report
+### Pork.autorun
 
-Report the summary from the tests. Usually you would want to call this at
-program exit, therefore most of the time you would want `Pork.report_at_exit`
-instead, unless you want to report the summary without exiting.
+Calling this would register an `at_exit` hook to run tests at exit.
+This also accepts an argument to turn on and off autorun. Calling this
+multiple times is ok. (It's not thread safe though, don't call this twice
+from different threads at the same time. If you really want to do this,
+let's add a mutex for this)
 
-Note that you would probably want to run `Pork.stats.start` at the beginning
-of your tests as well if you want to handle `Pork.report` manually.
+It would also exit with 0 if no error occurs or N for N errors and failures.
 
-### Pork.report_at_exit
+``` ruby
+Pork.autorun        # enable
+Pork.autorun(false) # disable
+Pork.autorun(true)  # enable
+```
 
-Basically simply call `Pork.stats.start` and setup `Pork.report` at exit,
-and exit with 0 if no error occurs or N for N errors and failures.
+`require 'pork/auto'` would call `Pork.autorun`
 
-If you also plan to pollute the top-level namespace so that you could simply
-call `describe` on top-level instead of calling it `Pork::API.describe`,
-you would probably want to simply `require 'pork/auto'` which is essentially:
+### Pork.execute_mode
+
+By default, `Pork.execute_mode` is set to `:execute`, which would
+execute all tests in a sequential manner. The other options are:
+
+* `:execute` (default)
+* `:shuffle`
+* `:parallel`
+
+With `:shuffle`, it would execute all tests in a random order. It would be
+slightly slower than `:execute`. With `:parallel`, it would run tests with
+8 threads concurrently, and of course, the orders are all random as well.
+You'll need to make sure your tests are thread safe or random tests would
+fail with this mode.
+
+Pass the symbol to it to use the mode:
 
 ``` ruby
-require 'pork'
-extend Pork::API
-Pork.report_at_exit
+Pork.execute_mode :shuffle
 ```
 
 ### Pork.inspect_failure_mode
@@ -683,13 +808,35 @@ really long, it would even use `diff` to show the difference.
 This is because if the actual string is long, it would be quite painful to
 find the actual difference for human without assistance.
 
+Additionally, if both the actually object and expected object are hashes,
+and if the actually hash is fairly large, it would also try to differentiate
+the two and give you a more readable result like:
+
+```
+Pork::Failure: Expect
+        Hash with key path: "categories:0:chats:0:mentor:username"
+"Expect Name".==("Actual Name") to return true
+```
+
+For this:
+
+``` ruby
+mentor = {"Some" => "Random", "Data" => "Here", "This's" => "Large"}
+expect("categories" => [{"chats" => [{"mentor" =>
+         mentor.merge("username" => "Actual Name")}]}]).eq \
+       "categories" => [{"chats" => [{"mentor" =>
+         mentor.merge("username" => "Expect Name")}]}]
+```
+
+This should much improve the time to figure out why it's failing.
+
 However, this might not really be desired at times. So we should be able to
 switch between each mode. For now, we have the following modes:
 
-* :auto (default)
-* :inline
-* :newline
-* :diff
+* `:auto` (default)
+* `:inline`
+* `:newline`
+* `:diff`
 
 If we want to force to a specific mode, here's how we would do:
 

data/Rakefile

@@ -10,5 +10,5 @@ Gemgem.init(dir) do |s|
   require 'pork/version'
   s.name    = 'pork'
   s.version = Pork::VERSION
-  %w[].each{ |g| s.add_runtime_dependency(g) }
+  %w[muack].each{ |g| s.add_development_dependency(g) }
 end

data/lib/mutant/integration/pork.rb

@@ -0,0 +1,76 @@
+
+require 'pork'
+require 'pork/isolate'
+require 'stringio'
+
+module Mutant
+  class Integration
+    class Pork < self
+      register 'pork'
+
+      # Return integration compatible to currently loaded pork
+      #
+      # @return [Integration]
+      #
+      # @api private
+      #
+      def self.build
+        new
+      end
+
+      # Setup pork integration
+      #
+      # @return [self]
+      #
+      # @api private
+      #
+      def setup
+        Dir['test/**/test_*.rb'].each do |path|
+          require "./#{path}"
+        end
+        ::Pork.autorun(false)
+        self
+      end
+      memoize :setup
+
+      # Return report for test
+      #
+      # @param [Pork::Test] test
+      #
+      # @return [Test::Result]
+      #
+      # @api private
+      #
+      # rubocop:disable MethodLength
+      #
+      def run(test)
+        stat = ::Pork::Executor.isolate(test.expression.syntax,
+                                        ::Pork::Stat.new(StringIO.new))
+
+        Result::Test.new(
+          test:     nil,
+          mutation: nil,
+          output:   stat.io.string,
+          runtime:  Time.now - stat.start,
+          passed:   stat.passed?
+        )
+      end
+
+      # Return all available tests
+      #
+      # @return [Enumerable<Test>]
+      #
+      # @api private
+      #
+      def all_tests
+        ::Pork::Executor.all_tests.keys.inject([]) do |tests, description|
+          expression = Expression.try_parse(description) or next tests
+          tests << Test.new(self, expression)
+        end
+      end
+      memoize :all_tests
+
+    end # Pork
+
+  end # Integration
+end # Mutant