bobbyno-shubox

= shubox - A framework to create sandboxes for test-driven learning

http://github.com/bobbyno/shubox/tree/master

More on Test-Driven Learning: http://www.bobbynorton.com/?p=36

== DESCRIPTION

Test-driven learning is a way to master a programming language by writing unit tests around its API's. shubox lowers the barrier to entry for test-driven learning by providing a basic infrastructure in which to start coding: A directory structure, some classes and unit tests to get started, and a build script.

shubox currently creates environments for Ruby and Java, but can easily be extended to any language that lends itself to unit testing. shubox is built on newgem, so extending the framework is as simple as creating new generator scripts.

After installing shubox and generating a testing environment, you'll start off with some passing tests that exercise parts of the language's API. Write new learning tests, naming each method with the intent of the lesson, then write the code that makes a test pass.

Can you complete the lesson again from memory? If not, you may need to study the concept more closely and implement the tests again. According to {a paper by Karpicke and Roediger}[http://psych.wustl.edu/memory/Roddy%20article%20PDF's/Karpicke_Roediger_2008_Science.pdf], "repeated retrieval practice led to greater than 150% improvements in long-term retention than studying alone. ...Although educators and psychologists often consider testing a neutral process that merely assesses the contents of memory, practicing retrieval during tests clearly produces more learning than additional encoding or study once an item has been recalled."

shubox makes repeated testing easy by providing built-in test cleaners that delete your test implementations, while keeping comments and test names to express the intent of the test.

== INSTALL

The shubox application is distributed as a RubyGem and is available immediately after installation.

$ gem sources -a http:http://gems.github.com

$ sudo gem install bobbyno-shubox

Alternately, download the gem and install manually from github.

== RUBY USAGE

Ruby is the default language option in shubox:

$ shubox /tmp/learn_ruby

$ cd /tmp/learn_ruby

$ rake

To clean all tests in your project:

$ script/clean_test_unit .

If you're using TextMate, you can quickly reset a test file from within the editor using "Text -> Filter Through Command". Select "/tmp/learn_ruby/script/filter_test_unit" as the command, select "Document" as input, and select "Replace Document" as output. Alternately, save the contents of the filter script to a custom TextMate command to easily run it with a keyboard shortcut.

== JAVA USAGE

shubox supports Java:

$ shubox -l=java /tmp/LearnJava

$ cd /tmp/LearnJava

$ ant -f build/build.xml

The Java command will also generate a .ipr file to allow the project to easily be opened in IntelliJ 8.

shubox does not currently include a JUnit cleaner script. Patches welcome. ;-)

== APPLICATION ARCHITECTURE

shubox is organized as a set of generators, as in newgem and RubiGen.

app_generators are where we define the basic environment for one of our supported languages.

cleaner_generators hold the test framework cleaning implementations to reset tests. In the future, these can be mixed and matched to support polyglots like JRuby by installing both JUnit and Test::Unit cleaners. Run script/generate in a generated shubox to see the list of available cleaners and generators that can be installed.

cleaner/lib folders hold the implementations of the cleaners referenced in the clean_xxx files copied to the generated application. This makes it easy to upgrade existing shuboxes.

== REQUIREMENTS

• newgem

== CONTRIBUTORS

Initial concept - Bobby Norton

bendyworks for {Test::Unit cleaner patch}[http://github.com/bendyworks/shubox]

== THANKS!

{DRW Trading Group}[http://www.drwtrading.com] for time and feedback

Test-Driven Learning Attendees at {SCNA 2009}[http://scna.softwarecraftsmanship.org/schedule#bobby_norton]

Dr. Nic Williams for newgem and rubigen: {RubyConf 2007 Presentation}[http://rubyconf2007.confreaks.com/d3t1p1_rubigen.html]

Jim Weirich and EdgeCase for {ruby_koans}[http://github.com/edgecase/ruby_koans]