oojspec 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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,174 @@
+# oojspec - Object-oriented client-side testing
+
+`oojspec` is a test runner built on top of [Buster.js](http://busterjs.org/), focused on
+integration tests. It is also a Rails engine, although you can use it in non-Rails
+applications - more on that in a later topic.
+
+It uses the same assertions and reporter and you can choose between expectations
+and assertions style on your examples or even mix them up.
+
+This is heavily inspired by another beloved tool called [RSpec](https://www.relishapp.com/rspec/),
+and also takes some inspiration from Jasmine and Buster.
+
+I really prefer writing expectations instead of assertions because I think it reads better. But
+on the other hand I find expectations an overkill for things like:
+
+```javascript
+expect(seats.length).toBeTruthy()
+```
+
+I'd rather prefer to write:
+
+```javascript
+assert(seats.length)
+```
+
+# Is it production ready?
+
+It should be, but its API is certainly going to change a lot before it becomes stable.
+
+So I wouldn't advise you to write tons of tests with `oojspec` because you might have to rewrite
+them in the future when the API changes.
+
+On the other side, I'll be using it myself in my own projects, replacing my Jasmine specs.
+
+# Where are its tests?
+
+I'm still not sure on how to properly test it. For the time being, I'm writing some examples
+in a separate project. I'll publish its link here as soon as I polish it.
+
+# Why not just using Buster.js (or Jasmine.js)?
+
+Jasmine.js doesn't support beforeAll/afterAll and that was the main motivation I started to develop
+another test runner. But let's be honest, I didn't want to maintain all expectations/assertions by
+myself. Also I didn't want to worry about the reporter. I just wanted to focus on the runner itself.
+
+Mocha/Chai seemed a great alternative but I had to support older Internet Explorer in my
+application while the syntax of Chai required a feature not supported by those browsers.
+
+Then I've heard about this excellent testing tool called Buster.js. It supported beforeAll/afterAll
+just like Mocha but it didn't give any guarantees about the order of execution of the tests and
+I needed that guarantee for some integration tests.
+
+But on the other side it is pretty modular and I would be able to take advantage of their
+assertions and expectations syntax as well as its reporter (although I'm still not happy with
+the default html reporter and I'll probably have to write a new one in the future).
+
+As Buster.js allowed me to focus on the runner itself I decided to begin this new project.
+
+Also I took the chance to do things the correct way in my opinion. I don't like the fact that most
+test runners (all of them?) will publish `describe`, `it`, `waitsFor` etc. independently from the
+context.
+
+In contrast `oojspec` will only export `describe`. The other allowed features will be available
+depending on the context. Inside a description `example`, `specify`, `it`, `xit`, `pending` and
+`describe` will be available. Inside an example `expect`, `assert`, `waitsFor` and `runs` will be
+available .
+
+# CoffeeScript?! Really?!
+
+JavaScript?! Really?!
+
+This is me who is writing this runner and I dislike JavaScript, so please keep your preferences
+for you. I won't change to pure JavaScript. Period.
+
+# Can I test my JavaScript code with oojspec despite it being written in CS?
+
+Of course. Why are you asking me that?
+
+On the other hand I'd advise you to write your examples in CoffeeScript for brevity.
+
+JavaScript example:
+
+```javascript
+oojspec.describe('Some description', function(){
+  this.example('Some example', function(){
+    this.assert(true)
+  })
+});
+```
+
+CoffeeScript version:
+
+```coffeescript
+oojspec.describe 'Some description', ->
+  @example 'Some example', -> @assert true
+```
+
+Alternatively, you can use some shortcut to `this` if you're using JavaScript:
+
+```javascript
+oojspec.describe('Some description', function(s){
+  s.example('Some example', function(s){
+    s.assert(true)
+  })
+});
+```
+
+But I'm not sure if this API will remain supported in the future although I don't currently have
+any plans to change it.
+
+# Usage with Rails
+
+`oojspec` is also a Rails engine built on top of
+[rails-sandbox-assets](https://github.com/rosenfeld/rails-sandbox-assets).
+
+It takes advantage of the Rails asset pipeline to run your specs. To launch the runner, after
+including `oojspec` to your Gemfile, run `rake sandbox_assets:serve`.
+
+It will load all your specs inside `(spec|test)/javascripts/oojspec/` named `*_spec.js[.coffee]`
+or `*_test.js[.coffee]`. Then run the examples by accessing http://localhost:5000/oojspec.
+
+If you want to put your specs directly on `spec/javascripts`, add this to your application.rb:
+
+```ruby
+config.sandbox_assets.template = 'oojspec/runner'
+```
+
+Then you'll be able to run the specs by directly accessing http://localhost:5000.
+
+By default this gem will expose `oojspec.describe` to the `window` object so that you can write it
+directly from the top-level, but you can disable this exposition if you prefer:
+
+```ruby
+config.sandbox_assets.options[:skipt_oojspec_expose] = true
+```
+
+# What about non-Rails applications?
+
+There are two ways you can use oojspec with non-Rails applications.
+
+If you want to take advantage of the Rails asset pipeline,
+[here](https://github.com/rosenfeld/jasmine_assets_enabler/tree/oojs)
+is an example on how to integrate the `rails-sandbox-assets` gem (and consequently this one) to
+your non-Rails application.
+
+It is target to the `oojs` gem that is currently built on top of `rails_sandbox_jasmine` but this
+is going to change and `oojs` will be built on top of `oojspec` in the future. But you can currently
+just add both gems right now and ignore the Jasmine runner while I don't change `oojs`.
+
+The other approach is to compile the source (possibly in the
+[Try CoffeeScript page](http://coffeescript.org/)) and write your own custom runner HTML. Just take
+the template provided by this gem as an example on how to write it.
+
+I hope to have more free time to write more in-depth examples on how to do that in the Wiki
+in the future.
+
+# Plans for the future
+
+There are so many but I'm not sure how long it will take to implement all of the intended
+features in my spare time.
+
+I'd like to support `given-and-when-and-then-and` style specs at some point.
+
+Also, I'm still thinking about a more object-oriented API for the description blocks.
+
+But I wanted to have some initial working version published soon before someone register an
+`oojspec` gem before me! :)
+
+# Contributing
+
+I'd love to hear your opinions on the API and design of `oojspec` and of course contributions
+will be very welcome if they're aligned with this project goals.
+
+Enjoy! :)

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Oojspec'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/app/views/oojspec/runner.html.erb

@@ -0,0 +1,25 @@
+<!doctype html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=utf-8">
+
+  <title>Buster.js Test Runner</title>
+
+  <%= stylesheet_link_tag "oojspec" %>
+  <%= javascript_include_tag "oojspec" %>
+  <%= javascript_tag "oojspec.exposeAll()" unless Rails.configuration.sandbox_assets.options[:skip_oojspec_expose] %>
+
+<% @stylesheets.each do |css| -%>
+  <%= stylesheet_link_tag css %>
+<% end -%>
+
+<% @tests.each do |test| -%>
+  <%= javascript_include_tag test %>
+<% end -%>
+</head>
+<body>
+
+  <%= javascript_tag "oojspec.autorun()" %>
+</body>
+</html>
+

data/lib/assets/javascripts/oojspec.js.coffee

@@ -0,0 +1,256 @@
+# =require buster/all
+
+window.oojspec = new class OojspecRunner
+  constructor: ->
+    @runner = buster.create buster.eventEmitter
+    @descriptions = []
+    @assertions = buster.assertions
+    (logFormatter = buster.create buster.format).quoteStrings = false
+    @assertions.format = buster.bind logFormatter, "ascii"
+    @assertions.on 'pass', => @stats.assertions++
+    @assertions.on 'failure', => @stats.failures++
+    #@runner.on 'context:start', => @stats.contexts++
+    @runner.on 'test:timeout', => @stats.timeouts++
+    @runner.on 'test:error', => @stats.errors++
+    @runner.on 'test:deferred', => @stats.deferred++
+
+    @stats =
+      contexts: 0
+      tests: 0
+      assertions: 0
+      errors: 0
+      failures: 0
+      timeouts: 0
+      deferred: 0
+
+  exposeAll: -> window.describe = @describe
+  autorun: -> @runSpecs() unless @disableAutorun
+
+  runSpecs: ->
+    @reporter = buster.reporters.html.create()
+    @reporter.listen @runner
+    @runner.emit 'suite:start', name: "Specs"
+    @runNextDescription()
+
+  runNextDescription: =>
+    (@runner.emit 'suite:end', @stats; return) unless @descriptions.length
+    # TODO: think about non null contexts usage
+    @descriptions.shift().run @runner, @assertions, null, @runNextDescription
+
+  describe: (description, block)=>
+    @stats.contexts++ # only root descriptions will be count
+    @descriptions.push new Description(description, block)
+
+class Description
+  RESERVED = ['beforeAll', 'before', 'after', 'afterAll', 'describe', 'context',
+              'example', 'it', 'specify', 'pending', 'xit']
+  constructor: (@description, @block)->
+
+  run: (@runner, @assertions, @context, @onFinish, @beforeBlocks = [], @afterBlocks = [])->
+    @runner.emit 'context:start', name: @description
+    @dsl = new DescribeDsl
+    if c = @context
+      for reserved in RESERVED
+        try
+          throw new Error("'#{reserved}' method is reserved for oojspec usage only") if c[reserved]
+        catch e
+          e.name = "syntax error"
+          @runner.emit 'test:error', name: @description, error: e
+          @onDescriptionFinished(e)
+        c[reserved] = @dsl[reserved]
+    @runAround @beforeBlocks, @afterBlocks, @onDescriptionFinished, @processDescriptionBlock
+
+  onDescriptionFinished: (error)=>
+    if error and not error.handled
+      error.handled = true
+      @runner.emit 'test:error', { name: 'Error running describe statements', error }
+    @runner.emit 'context:end'
+    @onFinish error
+
+  runAround: (befores, afters, onFinish, block)->
+    new AroundBlock(befores, afters, block).run @runner, @assertions, @context, onFinish
+
+  processDescriptionBlock: (onFinish)=>
+    context = @context or @dsl
+    @block.call context, context
+    @runAround @dsl._beforeAllBlocks_, @dsl._afterAllBlocks_, onFinish, (@onExamplesFinished)=>
+      @runNextStep()
+
+  runNextStep: =>
+    (@onExamplesFinished(); return) unless @dsl._examples_.length
+    nextStep = @dsl._examples_.shift()
+    (@reportDeferred(nextStep.description); @runNextStep(); return) if nextStep.pending
+    nextTick =
+      if nextStep instanceof Description then => nextStep
+        .run @runner, @assertions, @context, @runNextStep, @dsl._beforeBlocks_, @dsl._afterBlocks_
+      else => # ExampleWithHooks
+        nextStep.run @runner, @assertions, @context, @onExampleFinished
+    setTimeout nextTick, 0
+
+  onExampleFinished: (error)=>
+    (@runNextStep(); return) unless error and not error.handled
+    error.handled = true
+    console.log error
+    name = @description
+    name += " in #{error.source}" if error.source
+    @runner.emit 'test:error', { name, error }
+    @onFinish(error)
+
+  reportDeferred: (description)-> @runner.emit 'test:deferred', name: description
+
+class DescribeDsl
+  addHook = (description, block, container)->
+    if typeof description is 'string'
+      return unless block # pending hook
+      block.description = description
+    else
+      block = description
+    container.push block
+
+  constructor: ->
+    @_beforeAllBlocks_ = []
+    @_beforeBlocks_ = []
+    @_afterBlocks_ = []
+    @_afterAllBlocks_ = []
+    @_examples_ = []
+    # aliases:
+    @it = @specify = @example
+    @context = @describe
+    @xit = @pending
+
+  beforeAll: (description, block)=> addHook description, block, @_beforeAllBlocks_
+  before:    (description, block)=> addHook description, block, @_beforeBlocks_
+  after:     (description, block)=> addHook description, block, @_afterBlocks_
+  afterAll:  (description, block)=> addHook description, block, @_afterAllBlocks_
+  describe:  (description, block)=>
+    @_examples_.push new Description(description, block, @_beforeBlocks_, @_afterBlocks_)
+  example:   (description, block)=>
+    @_examples_.push new ExampleWithHooks(description, @_beforeBlocks_, @_afterBlocks_, block)
+  pending:   (description)=> @_examples_.push {description, pending: true}
+
+class AroundBlock
+  constructor: (@beforeBlocks, @afterBlocks, @block)->
+
+  run: (@runner, @assertions, @context, @onFinish)->
+    @runGroup @beforeBlocks, ((e)=> @onBeforeError e), (wasSuccessful)=>
+      if wasSuccessful
+        @runMainBlock @block, (error)=>
+          @registerError error
+          @runAfterGroup()
+      else @runAfterGroup()
+
+  registerError: (error)->
+    @runner.emit 'oojspec:log:error', error
+    @error or= error
+
+  runMainBlock: (block, onFinish)->
+    try
+      block onFinish
+    catch error
+      error = new Error(error) if typeof error is 'string'
+      @registerError error
+      onFinish error
+
+  runGroup: (group, onError, onFinish)->
+    new ExampleGroupWithoutHooks(@assertions, @context, group, onFinish, onError).run()
+
+  onBeforeError: (error)-> error.source = "before hook"; @registerError error
+  onAfterError:  (error)-> error.source = "after hook";  @registerError error
+  runAfterGroup: -> @runGroup @afterBlocks, ((e)=> @onAfterError e), (=> @onAfterHooks())
+  onAfterHooks: -> @onFinish @error
+
+class ExampleWithHooks extends AroundBlock
+  constructor: (@description, @beforeBlocks, @afterBlocks, @block)->
+  runMainBlock: (block, onFinish)-> new Example(block).run @assertions, @context, onFinish
+  onAfterHooks: ->
+    @handleResult()
+    super
+
+  handleResult: ->
+    (@runner.emit 'test:success', name: @description; return) unless @error
+    @error.handled = true
+    if @error.name is 'AssertionError'
+      @runner.emit 'test:failure', name: @description, error: @error
+      return
+
+    if @error.timeout
+      @error.source or= 'example'
+      @runner.emit 'test:timeout', name: @description, error: @error
+      return
+    @error.name = 'Exception'
+    @error.name += " in #{@error.source}" if @error.source
+    @runner.emit 'test:error', name: @description, error: @error
+
+class ExampleGroupWithoutHooks
+  constructor: (@assertions, @context, @blocks, @onFinish, @onError)-> @nextIndex = 0
+
+  run: ->
+    @wasSuccessful = true
+    setTimeout @nextTick, 0
+
+  nextTick: =>
+    (@onFinish(@wasSuccessful); return) unless @nextIndex < @blocks.length
+    block = @blocks[@nextIndex++]
+    new Example(block).run @assertions, @context, (error)=>
+      (@wasSuccessful = false; @onError error) if error
+      setTimeout @nextTick, 0
+
+class Example
+  TICK = 10 # ms
+  constructor: (@exampleBlock)->
+
+  run: (@assertions, @context, @onFinish)->
+    @dsl = new ExampleDsl(@assertions.assert, @assertions.expect, @assertions.fail, \
+                          @assertions.refute)
+    if @context
+      throw "runs and waitsFor are reserved attributes" if @context.runs or @context.waitsFor
+      @context.runs = @dsl.runs
+      @context.waitsFor = @dsl.waitsFor
+    @tryBlock @exampleBlock, ->
+      if @context
+        delete @context.runs
+        delete @context.waitsFor
+      (@onFinish(); return) unless (@steps = @dsl._asyncQueue_).length
+      @runNextAsyncStep()
+
+  tryBlock: (block, onSuccess)->
+    try
+      context = @context or @dsl
+      onSuccess.call this, block.call context, context
+    catch error
+      error = new Error(error) if typeof error is 'string'
+      error.message = "'#{error.message}' in '#{block.description}'" if block.description
+      @onFinish error
+
+  runNextAsyncStep: ->
+    (@onFinish(); return) unless @steps.length
+    step = @steps.shift()
+    if step instanceof Function
+      @tryBlock step, @runNextAsyncStep
+    else
+      @waitsFor step...
+
+  waitsFor: (@condition, timeout=1000, @description)->
+    @deadline = timeout + new Date().getTime()
+    @keepTryingCondition()
+
+  keepTryingCondition: =>
+    @tryBlock @condition, (result)->
+      (@runNextAsyncStep(); return) if result
+      (@onFinish {timeout: true, @description}; return) if new Date().getTime() > @deadline
+      setTimeout @keepTryingCondition, TICK
+
+class ExampleDsl
+  constructor: (@assert, @expect, @fail, @refute)-> @_asyncQueue_ = []
+
+  runs: (step)=> @_asyncQueue_.push step
+
+  waitsFor: =>
+    for a in arguments
+      (condition = a; continue)   if typeof a is "function"
+      (timeout = a; continue)     if typeof a is "number"
+      (description = a; continue) if typeof a is "string"
+    @_asyncQueue_.push [condition, timeout, description]
+
+class StepContext
+  constructor: (@assert, @expect, @fail)->

data/lib/assets/stylesheets/oojspec.css.erb

@@ -0,0 +1,5 @@
+/* =require buster/buster-test */
+/* override background image for supporting IE7 */
+.buster-test h1 .buster-logo {
+  background-image: url(<%= asset_path "buster/logo.png" %>);
+}

data/lib/oojspec/engine.rb

@@ -0,0 +1,15 @@
+module Oojspec
+  class OojspecFilter
+    def self.filter(controller)
+      controller.template = 'oojspec/runner' if controller.params[:path].try :start_with?, 'oojspec'
+    end
+  end
+
+  class Engine < ::Rails::Engine
+    initializer 'sandbox_assets.oojspec' do |app|
+      unless app.config.sandbox_assets.template == 'oojspec/runner'
+        SandboxAssets::BaseController.prepend_before_filter OojspecFilter
+      end
+    end
+  end
+end

data/lib/oojspec/version.rb

@@ -0,0 +1,3 @@
+module Oojspec
+  VERSION = "0.0.1"
+end

data/lib/oojspec.rb

@@ -0,0 +1,5 @@
+require "oojspec/engine"
+require "rails-sandbox-assets"
+
+module Oojspec
+end

data/lib/tasks/oojspec_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :oojspec do
+#   # Task goes here
+# end

data/vendor/assets/javascripts/buster/all.js.coffee

@@ -0,0 +1,3 @@
+# =require ./buster-core
+# =require ./buster-event-emitter
+# =require_tree .