btakita-screw_unit 0.1.0

data/CHANGES

@@ -0,0 +1,2 @@
+0.1.0
+- Initial Releast

data/README

@@ -0,0 +1,147 @@
+# Screw Unit
+The Screw Unit ruby library is a server runner for the Screw Unit javascript library.
+
+# Installing Screw Unit
+You can use Screw Unit as a gem or as a Rails plugin.
+To install the gem, run:
+  sudo gem install screw_unit
+
+To install the plugin, run:
+  script/plugin install git://github.com/btakita/screw-unit-server.git
+  script/generate screw_unit
+
+The Rails plugin gives you generators when using Screw Unit in a Rails environment.
+
+# Running Screw Unit Server
+First you need to start your Screw Unit server.
+
+If you are using screw_unit_server as a Rails plugin, you can simply run:
+  script/screw_unit_server
+
+If you are using the screw_unit gem, you can run:
+  screw_unit_server /path/to/your/javascript/spec/files /path/to/your/javascript/implementation/files
+
+Once the server is started, there are two possibly ways to run your js spec:
+  * Open your browser to http://localhost:8080/specs
+  * Start the Selenium server by running `selenium` from the command line, then running `screw_unit` from the command line
+
+# Screw Unit on CI
+JS spec uses the Selenium gem to automatically control browsers on different machines.
+
+To use Screw Unit in a CI environment,
+  * Install and run the selenium RC server on the machine that you want to run the browsers by using the command:
+    selenium
+  * Run the screw_unit_server on the machine that has the files.
+    script/screw_unit_server
+  * Run the screw_unit client. The screw_unit client has --selenium_host, --selenium_port, and --spec_url arguments to specify
+    where the Selenium server is relative to the screw_unit server, and where the screw_unit server is relative to the browser.
+
+# Screw Unit Library
+
+Screw.Unit is a Behavior-Driven Testing Framework for Javascript written by Nathan Sobo and Nick Kallen. It features nested describes. Its goals are to provide:
+
+* a DSL for elegant, readable, organized specs;
+* an interactive runner which can execute focused specs and describes;
+* and brief, extensible source-code.
+
+# What it is
+
+![Test Runner](http://s3.amazonaws.com/assets.pivotallabs.com/87/original/runner.png)
+
+The testing language is inspired by JSpec (and Rspec, obviously). Consider,
+
+    describe("Matchers", function() {
+      it("invokes the provided matcher on a call to expect", function() {
+        expect(true).to(equal, true);
+        expect(true).to_not(equal, false);
+      });
+    });
+
+A key feature of Screw.Unit are nested `describes` and the cascading `before` behavior that entails:
+
+    describe("a nested describe", function() {
+      var invocations = [];
+
+      before(function() {
+        invocations.push("before");
+      });
+
+      describe("a doubly nested describe", function() {
+        before(function() {
+          invocations.push('inner before');
+        });
+
+        it("runs befores in all ancestors prior to an it", function() {
+          expect(invocations).to(equal, ["before", "inner before"]);
+        });
+      });
+    });
+
+The Screw.Unit runner is pretty fancy, supporting focused `describes` and focused `its`:
+
+![Focused Runner](http://s3.amazonaws.com/assets.pivotallabs.com/86/original/focused.png)
+
+You can [download the source](http://github.com/nkallen/screw-unit/tree/master) from Github. Please see the included spec (`screwunit_spec.js`) to get up and running.
+
+# Implementation Details
+
+Screw.Unit is implemented using some fancy metaprogramming learned from the formidable Yehuda Katz. This allows the `describe` and `it` functions to not pollute the global namespace. Essentially, we take the source code of your test and wrap it in a with block which provides a new scope:
+
+    var contents = fn.toString().match(/^[^\{]*{((.*\n*)*)}/m)[1];
+    var fn = new Function("matchers", "specifications",
+      "with (specifications) { with (matchers) { " + contents + " } }"
+    );
+
+    fn.call(this, Screw.Matchers, Screw.Specifications);
+
+Furthermore, Screw.Unit is implemented using the **Concrete Javascript** style, which is made possible by the [Effen plugin](http://github.com/nkallen/effen/tree/master) and jQuery. Concrete Javascript is an alternative to MVC. In Concrete Javascript, DOM objects serve as the model and view simultaneously. The DOM is constructed using semantic (and visual) markup, and behaviors are attached directly to DOM elements. For example,
+
+    $('.describe').fn({
+      parent: function() {
+        return $(this).parent('.describes').parent('.describe');
+      },
+      run: function() {
+        $(this).children('.its').children('.it').fn('run');
+        $(this).children('.describes').children('.describe').fn('run');
+      },
+    });
+
+Here two methods (`#parent` and `#run`) are attached directly to DOM elements that have class `describe`. To invoke one of these methods, simply:
+
+    $('.describe').fn('run');
+
+Bind behaviors by passing a hash (see the previous example). Using CSS3 selectors and cascading to attach behaviors provides interesting kind of multiple inheritance and polymorphism:
+
+    $('.describe, .it').fn({...}); // applies to both describe and its
+    $('.describe .describe').fn({...}); // applies to nested describes only
+
+A typical Concrete Javascript Application is divided into 4 aspects:
+
+* a DOM data model,
+* CSS bound to DOM elements,
+* asynchronous events bound to DOM elements (`click`, `mouseover`), etc.,
+* synchronous behaviors bound to DOM elements (`run` and `parent` in the above example).
+
+The Concrete style is particularly well-suited to Screw.Unit; to add the ability to run a focused spec, we simply bind a click event to an `it` or a `describe`, which runs itself:
+
+    $('.describe, .it')
+      .click(function() {
+        $(this).fn('run');
+      })
+
+Anyway, more details about Effen / Concrete Javascript in a later post.
+
+# Extensibility
+
+Screw.Unit is designed from the ground-up to be extensible. For example, to add custom logging, simply subscribe to certain events:
+
+    $('.it')
+      .bind('enqueued', function() {...})
+      .bind('running', function() {...})
+      .bind('passed', function() {...})
+      .bind('failed', function(e, reason) {...})
+
+# Thanks to
+
+* Nathan Sobo
+* Yehuda Katz

data/Rakefile

@@ -0,0 +1,70 @@
+require "rake"
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc "Runs the Rspec suite"
+task(:default) do
+  run_suite
+end
+
+desc "Runs the Rspec suite"
+task(:spec) do
+  run_suite
+end
+
+desc "Copies the trunk to a tag with the name of the current release"
+task(:tag_release) do
+  tag_release
+end
+
+def run_suite
+  dir = File.dirname(__FILE__)
+  system("ruby #{dir}/spec/spec_suite.rb") || raise("Example Suite failed")
+end
+
+PKG_NAME = "screw_unit"
+PKG_VERSION = "0.1.0"
+PKG_FILES = FileList[
+  '[A-Z]*',
+  '*.rb',
+  'lib/**/*.rb',
+  'core/**',
+  'bin/**',
+  'spec/**/*.rb'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "The ScrewUnit client library (http://github.com/nkallen/screw-unit) plus a convenient ruby server."
+  s.test_files = "spec/spec_suite.rb"
+  s.description = s.summary
+
+  s.files = PKG_FILES.to_a
+  s.require_path = 'lib'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = [ "README", "CHANGES" ]
+  s.rdoc_options = ["--main", "README", "--inline-source", "--line-numbers"]
+
+  s.test_files = Dir.glob('spec/*_spec.rb')
+  s.require_path = 'lib'
+  s.author = "Brian Takita"
+  s.email = "brian@pivotallabs.com"
+  s.homepage = "http://pivotallabs.com"
+  s.rubyforge_project = "pivotalrb"
+  s.add_dependency('Selenium')
+  s.add_dependency('thin', '>=0.8.0')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+def tag_release
+  system("git tag #{dashed_version} -m 'Version #{PKG_VERSION}'")
+end

data/bin/screw_unit

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift("#{dir}/../lib")
+require "screw_unit"
+exit ScrewUnit::Client.run_argv(ARGV)

data/bin/screw_unit_server

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift("#{dir}/../lib")
+require "screw_unit"
+
+spec_root_path = ARGV[0] || raise("You need to pass in a spec root")
+implementation_root_path = ARGV[1] || raise("You need to pass in an implementation root")
+public_path = ARGV[2] || raise("You need to pass in a public path")
+ScrewUnit::Server.run(spec_root_path, implementation_root_path, public_path)

data/core/README.markdown

@@ -0,0 +1,107 @@
+Screw.Unit is a Behavior-Driven Testing Framework for Javascript written by Nathan Sobo and Nick Kallen. It features nested describes. Its goals are to provide:
+
+* a DSL for elegant, readable, organized specs;
+* an interactive runner which can execute focused specs and describes; 
+* and brief, extensible source-code.
+
+# What it is
+
+![Test Runner](http://s3.amazonaws.com/assets.pivotallabs.com/87/original/runner.png)
+
+The testing language is inspired by JSpec (and Rspec, obviously). Consider,
+
+    describe("Matchers", function() {
+      it("invokes the provided matcher on a call to expect", function() {
+        expect(true).to(equal, true);
+        expect(true).to_not(equal, false);
+      });
+    });
+
+A key feature of Screw.Unit are nested `describes` and the cascading `before` behavior that entails:
+
+    describe("a nested describe", function() {
+      var invocations = [];
+      
+      before(function() {
+        invocations.push("before");
+      });
+
+      describe("a doubly nested describe", function() {
+        before(function() {
+          invocations.push('inner before');
+        });
+
+        it("runs befores in all ancestors prior to an it", function() {
+          expect(invocations).to(equal, ["before", "inner before"]);
+        });
+      });
+    });
+    
+The Screw.Unit runner is pretty fancy, supporting focused `describes` and focused `its`:
+
+![Focused Runner](http://s3.amazonaws.com/assets.pivotallabs.com/86/original/focused.png)
+
+You can [download the source](http://github.com/nkallen/screw-unit/tree/master) from Github. Please see the included spec (`screwunit_spec.js`) to get up and running.
+
+# Implementation Details
+
+Screw.Unit is implemented using some fancy metaprogramming learned from the formidable Yehuda Katz. This allows the `describe` and `it` functions to not pollute the global namespace. Essentially, we take the source code of your test and wrap it in a with block which provides a new scope:
+
+    var contents = fn.toString().match(/^[^\{]*{((.*\n*)*)}/m)[1];
+    var fn = new Function("matchers", "specifications",
+      "with (specifications) { with (matchers) { " + contents + " } }"
+    );
+
+    fn.call(this, Screw.Matchers, Screw.Specifications);
+
+Furthermore, Screw.Unit is implemented using the **Concrete Javascript** style, which is made possible by the [Effen plugin](http://github.com/nkallen/effen/tree/master) and jQuery. Concrete Javascript is an alternative to MVC. In Concrete Javascript, DOM objects serve as the model and view simultaneously. The DOM is constructed using semantic (and visual) markup, and behaviors are attached directly to DOM elements. For example,
+
+    $('.describe').fn({
+      parent: function() {
+        return $(this).parent('.describes').parent('.describe');
+      },
+      run: function() {
+        $(this).children('.its').children('.it').fn('run');
+        $(this).children('.describes').children('.describe').fn('run');
+      },
+    });
+
+Here two methods (`#parent` and `#run`) are attached directly to DOM elements that have class `describe`. To invoke one of these methods, simply:
+
+    $('.describe').fn('run');
+
+Bind behaviors by passing a hash (see the previous example). Using CSS3 selectors and cascading to attach behaviors provides interesting kind of multiple inheritance and polymorphism:
+
+    $('.describe, .it').fn({...}); // applies to both describe and its
+    $('.describe .describe').fn({...}); // applies to nested describes only
+
+A typical Concrete Javascript Application is divided into 4 aspects:
+
+* a DOM data model,
+* CSS bound to DOM elements,
+* asynchronous events bound to DOM elements (`click`, `mouseover`), etc.,
+* synchronous behaviors bound to DOM elements (`run` and `parent` in the above example).
+
+The Concrete style is particularly well-suited to Screw.Unit; to add the ability to run a focused spec, we simply bind a click event to an `it` or a `describe`, which runs itself:
+
+    $('.describe, .it')
+      .click(function() {
+        $(this).fn('run');
+      })
+
+Anyway, more details about Effen / Concrete Javascript in a later post.
+
+# Extensibility
+
+Screw.Unit is designed from the ground-up to be extensible. For example, to add custom logging, simply subscribe to certain events:
+
+    $('.it')
+      .bind('enqueued', function() {...})
+      .bind('running', function() {...})
+      .bind('passed', function() {...})
+      .bind('failed', function(e, reason) {...})
+
+# Thanks to
+
+* Nathan Sobo
+* Yehuda Katz

data/core/TODO

@@ -0,0 +1,2 @@
+need a way to do global before and afters
+need to investigate race condition with data store