pork 0.1.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bcad9c9f6829b54485ba10be4c5f66f353c55b15
-  data.tar.gz: e4e717a01aa1816bbdcb916d55cb062cc1f0ca34
+  metadata.gz: 0720abd3578e820759c2cec35d565a41e41d6f79
+  data.tar.gz: 3abb0dc9d216004aa1fa11590fef142671111168
 SHA512:
-  metadata.gz: edcf6930fe9463137140ef9ed0f6ff7693d6d45d710c15a86fe8332e9ac8d2e60b37b7d39467ecf09c86d7dfe82ea60d229ed1a231c2dcc1519bdadf0de57220
-  data.tar.gz: ab819c314b0fbca15889e258fefadb68238d50bded7fa105a4fa882216038cbb5140959e8cf6bb7eeb05f8a00634740b1b54ac612987f05527307a44470998eb
+  metadata.gz: 6387d2c2049e7bbab044bcfba005616e3a236b9f58f2303c06fbd6b47613ee277c8219f098b49671e5011f94c3dab80aa449ffa8effb139da8885a1fc138355f
+  data.tar.gz: e4e2189fc58eede08bdcf3d65580ef1728474728fce82db3dae57f5ab013b6611b4385b5b16700ab54feba4b97e9cd1ed18470ea05ad633622f78222bdbc09a4

data/.gitignore

@@ -0,0 +1 @@
+/pkg/

data/CHANGES.md

@@ -0,0 +1,9 @@
+# CHANGES
+
+## Pork 0.9.0 -- 2014-07-11
+
+* First serious release! Bunch of updates. Nearly complete.
+
+## Pork 0.1.0 -- 2014-07-09
+
+* Birthday!

data/README.md

@@ -10,13 +10,140 @@ by Lin Jen-Shin ([godfat](http://godfat.org))
 
 ## DESCRIPTION:
 
-[Bacon][] reimplemented in an even more lightweight manner.
+Pork -- Simple and clean and modular testing library.
+
+[Bacon][] reimplemented around 250 lines of code.
 
 [Bacon]: https://github.com/chneukirchen/bacon
 
+## DESIGN:
+
+* Consistency over convenience.
+* Avoid polluting anything by default to make integration easier.
+* The less codes the better.
+
 ## WHY?
 
-[Bacon][] has some issues which can't be easily worked around.
+[Bacon][] has some issues which can't be easily worked around. For example,
+the context of the running test is not consistent in nested describe block.
+
+This won't work in Bacon:
+
+``` ruby
+require 'bacon'
+Bacon.summary_on_exit
+
+# This would include to all context,
+# so that we don't have to include in all describe block.
+Bacon::Context.include Module.new{
+  def in_module
+    object_id
+  end
+}
+
+describe 'A' do
+  def in_describe
+    object_id
+  end
+
+  describe 'B' do
+    should 'have the same context' do
+      in_module.should == in_describe # FAIL!
+    end
+  end
+end
+```
+
+But this works in Pork:
+
+``` ruby
+require 'pork/auto'
+
+describe 'A' do
+  include Module.new{
+    def in_module
+      object_id
+    end
+  }
+
+  def in_describe
+    object_id
+  end
+
+  describe 'B' do
+    would 'have the same context' do
+      in_module.should == in_describe
+    end
+
+    def in_nested_describe
+      object_id
+    end
+
+    would 'respond_to? in_nested_describe' do
+      should.respond_to?(:in_nested_describe)
+    end
+  end
+
+  # Pork is completely tree structured, nested methods can't be accessed
+  # from outside of the scope.
+  would 'not respond_to? in_nested_describe' do
+    should.not.respond_to?(:in_nested_describe)
+  end
+end
+
+describe 'C' do
+  # Also, we're not forced to include something in all describe blocks.
+  # If we want, we could do this instead: `Pork::Executor.include(Module.new)`
+  # That would be the same as including in `Bacon::Context`
+  would 'not respond_to? in_module nor in_describe' do
+    should.not.respond_to?(:in_module)
+    should.not.respond_to?(:in_describe)
+  end
+end
+```
+
+Also, Bacon won't clear instance variables as well.
+
+``` ruby
+require 'bacon'
+Bacon.summary_on_exit
+
+describe 'instance variables in tests' do
+  before do
+    @a ||= 0
+    @a  += 1
+  end
+
+  should 'always be 1' do
+    @a.should == 1
+  end
+
+  should 'always be 1' do
+    @a.should == 1 # FAIL!
+  end
+end
+```
+
+Every tests would be a whole new instance for Pork as expected:
+
+``` ruby
+require 'pork/auto'
+
+describe 'instance variables in tests' do
+  before do
+    @a ||= 0
+    @a  += 1
+  end
+
+  would 'always be 1' do
+    @a.should == 1
+  end
+
+  would 'always be 1' do
+    @a.should == 1
+  end
+end
+```
 
 ## REQUIREMENTS:
 
@@ -28,6 +155,457 @@ by Lin Jen-Shin ([godfat](http://godfat.org))
 
 ## SYNOPSIS:
 
+A simple example:
+
+``` ruby
+require 'pork/auto'
+
+describe Array do
+  before do
+    @array = []
+  end
+
+  after do
+    @array.clear
+  end
+
+  would 'be empty' do
+    @array.should.empty?
+    @array.should.not.include? 1
+  end
+
+  would 'have zero size' do
+    # We prefer `eq` here over `==` to avoid warnings from Ruby
+    @array.size.should.eq 0
+  end
+
+  would 'raise IndexError for fetching from non-existing index' do
+    should.raise(IndexError){ @array.fetch(0) }.message.
+      should.match(/\d+/)
+
+    # Alternatively:
+    lambda{ @array.fetch(0) }.should.raise(IndexError).message.
+      should.match(/\d+/)
+  end
+end
+```
+
+Copy and paste for modularity:
+
+``` ruby
+require 'pork/auto'
+
+copy 'empty test' do |error|
+  after do
+    @data.clear
+  end
+
+  would 'be empty' do
+    @data.should.empty?
+    @data.should.not.include? 1
+  end
+
+  would 'have zero size' do
+    # We prefer `eq` here over `==` to avoid warnings from Ruby
+    @data.size.should.eq 0
+  end
+
+  would "raise #{error} for fetching from non-existing index" do
+    should.raise(error){ @data.fetch(0) }.message.
+      should.match(/\d+/)
+
+    # Alternatively:
+    lambda{ @data.fetch(0) }.should.raise(error).message.
+      should.match(/\d+/)
+  end
+end
+
+describe Array do
+  before do
+    @data = []
+  end
+
+  paste 'empty test', IndexError
+end
+
+describe Hash do
+  before do
+    @data = {}
+  end
+
+  paste 'empty test', KeyError
+end
+```
+
+Context sensitive paste:
+
+``` ruby
+require 'pork/auto'
+
+copy 'empty test' do |error|
+  paste :setup_data # it would search from the pasted context
+
+  would "raise #{error} for fetching from non-existing index" do
+    should.raise(error){ @data.fetch(0) }.message.
+      should.match(/\d+/)
+  end
+end
+
+describe Array do
+  copy :setup_data do
+    before do
+      @data = []
+    end
+  end
+
+  paste 'empty test', IndexError
+end
+
+describe Hash do
+  copy :setup_data do
+    before do
+      @data = {}
+    end
+  end
+
+  paste 'empty test', KeyError
+end
+```
+
+## The API
+
+### Pork::API.describe
+
+So this creates a test suite which should be containing various test cases
+(`Pork::API.would`). The argument represents the description of the test
+suite, which accepts anything could be converted to a string. The _default_
+description is `:default` (which would be converted to `'default: '`)
+
+Each `describe` block would create a new subclass of `Pork::Executor` for
+isolating test suites. Each nested `describe` block would be a subclass of
+its parent `Pork::Executor`.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  would 'be default: for the default description' do
+    self.class.desc.should.eq 'default: '
+  end
+end
+```
+
+### Pork::API.would
+
+Essentially runs a test case. It could also be called in the top-level
+without being contained in a `describe` block. The argument represents the
+description of the test case, which accepts anything could be converted to
+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).
+You would probably want to setup stuffs inside `before` blocks.
+
+Each nested `describe` would also run parents' `before` blocks as well.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  before do
+    @a = 0
+  end
+
+  describe do
+    before do
+      @a.should.eq 0
+      @a += 1
+    end
+
+    would do
+      @a.should.eq 1
+    end
+  end
+end
+```
+
+### Pork::API.after
+
+Each `after` block would be called after each `would` block (test case).
+You would probably want to cleanup stuffs inside `after` blocks.
+
+Each nested `describe` would also run parents' `after` block as well.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  after do
+    @a.should.eq 1
+    @a += 1
+  end
+
+  describe do
+    after do
+      @a.should.eq 2
+    end
+
+    would do
+      @a = 1
+      @a.should.eq 1
+    end
+  end
+end
+```
+
+### Pork::API.copy and Pork::API.paste
+
+It could be a bit confusing at first, but just think of `copy` as a way to
+store the block with a name (default is `:default`), and whenever we `paste`,
+the stored block would be called at the context where we paste.
+
+The name could be anything, strings, symbols, numbers, classes, anything.
+
+The block passed to `copy` could have parameters. The second through the last
+arguments passed to `paste` would be passing to the block saved in copy.
+
+``` ruby
+require 'pork/auto'
+
+copy :default do |a=0, b=1|
+  before do
+    @a, @b = a, b
+  end
+
+  def f
+    @a + @b
+  end
+end
+
+describe do
+  paste :default, 1, 0
+
+  would do
+    f.should.eq 1
+  end
+end
+```
+
+### Pork::Executor#skip
+
+At times we might want to skip some tests while leave the codes there without
+removing them or commenting them out. This is where `skip` would be helpful.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  would do
+    skip
+  end
+end
+```
+
+### Pork::Executor#ok
+
+Because Pork would complain if a test case does not have any assertions,
+sometimes we might want to tell Pork that it's ok because we've already
+made some assertions without using Pork's assertions. Then we'll want `ok`.
+
+The reason why complaining about missing assertions is useful is because
+sometimes we might expect some assertions would be made in a certain flow.
+If the flow is not correctly called, we could miss assertions. So it's good
+to explicitly claim that we don't care about assertions rather than letting
+them slip through implicitly.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  would do
+    'verify with mocks, and pork has no idea about that'.to_s
+    ok
+  end
+end
+```
+
+### Pork::Executor#flunk
+
+If we're writing program carefully, there are a few cases where a condition
+would never meet. We could `raise "IMPOSSIBLE"` or we could simply call
+`flunk`.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  would do
+    should.raise(Pork::Error){ flunk }
+  end
+end
+```
+
+### Pork::Should#satisfy
+
+If we want to have custom verifier, that is it.
+
+``` ruby
+require 'pork/auto'
+
+describe do
+  divided_by_2 = lambda{ |n| n % 2 == 0 }
+
+  would do
+    2.should.satisfy(&divided_by_2)
+  end
+end
+```
+
+### Pork::Should#not
+
+An easy way to negate the expectation.
+
+``` ruby
+require 'pork/auto'
+
+would{ 1.should.not.eq 2 }
+```
+
+### Pork::Should#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.
+
+``` ruby
+require 'pork/auto'
+
+would{ 1.should.eq 1 }
+```
+
+### Pork::Should#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.
+
+``` ruby
+require 'pork/auto'
+
+would{ 1.should.lt 2 }
+```
+
+### Pork::Should#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.
+
+``` ruby
+require 'pork/auto'
+
+would{ 1.should.gt 0 }
+```
+
+### Pork::Should#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.
+
+``` ruby
+require 'pork/auto'
+
+would{ 1.should.lte 1 }
+```
+
+### Pork::Should#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.
+
+``` ruby
+require 'pork/auto'
+
+would{ 1.should.gte 1 }
+```
+
+### Pork::Should#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
+as the questioning expression.
+
+``` ruby
+require 'pork/auto'
+
+describe 'Pork::Should#raise' do
+  would 'check with a block' do
+    e = should.raise(RuntimeError){ raise "nnf" }
+    e.should.message.include?("nnf")
+  end
+
+  would 'check with a lambda' do
+    e = lambda{ raise "nnf" }.should.raise(RuntimeError)
+    e.should.message.include?("nnf")
+  end
+end
+```
+
+### Pork::Should#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
+simply pass a block as the questioning expression.
+
+``` ruby
+require 'pork/auto'
+
+describe 'Pork::Should#throw' do
+  would 'check with a block' do
+    e = should.throw(:nnf){ throw :nnf, 0 }
+    e.should.eq [:nnf, 0]
+  end
+
+  would 'check with a lambda' do
+    e = lambda{ throw :nnf, 1 }.should.throw(:nnf)
+    e.should.eq [:nnf, 1]
+  end
+end
+```
+
+### Pork.report
+
+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.
+
+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.
+
+### Pork.report_at_exit
+
+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.
+
+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:
+
+``` ruby
+require 'pork'
+extend Pork::API
+Pork.report_at_exit
+```
+
 ## CONTRIBUTORS:
 
 * Lin Jen-Shin (@godfat)