sniff 0.0.5 → 0.0.6

data/README.markdown

@@ -1,77 +1,58 @@
 # sniff
-Testing environment for Brighter Planet Climate Middleware emission calculation gems.
-
-This gem provides:
- * Sample data used for calculations, representative of data found on http://data.brighterplanet.com
- * A database/ActiveRecord environment for said data
- * References to gems needed by each emitter gem  
- * An autoloader that will load any models and sample data needed by the emitter gem being tested (see Usage)
-
-# Usage
-Within an emitter gem's test setup, you can:
-    require 'sniff'
-    
-    Sniff.init '/path/to/emitter_project'
-
-If an emitter gem has its own test models and data, sniff will look for the models in `EMITTER_GEM_DIR/lib/test_support/data_models/` and the data fixtures in `EMITTER_GEM_DIR/lib/test_support/db/fixtures/`. It will also look for a schema in `EMITTER_GEM_DIR/lib/test_support/db/schema.rb`
-
-# How to contribute
-Typical contributions will include updates to test data.
-
-1. Fork the project.
-1. Make your feature addition or bug fix.
-1. Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-1. Send me a pull request. Bonus points for topic branches.
-
-# Local Gems
-Sniff depends on several gems, some of which are developed by Brighter Planet.  You can tell Sniff or any of the carbon gems to use your local repos in lieu of installed rubygems through the following steps:
-
-
-Paste the following functions into your ~/.bash_profile
-    function mod_devgem() {
-      var="LOCAL_`echo $2 | tr 'a-z' 'A-Z'`"
-      
-      if [ "$1" == "disable" ]
-      then
-        echo "unset $var"
-        unset $var
-      else
-        dir=${3:-"~/$2"}
-        echo "export $var=$dir"
-        export $var=$dir
-      fi
-    }
-    
-    function devgems () {
-      # Usage: devgems [enable|disable] [gemname]
-      cmd=${1:-"enable"}
-      if [ -z $2 ]
-      then
-        mod_devgem $cmd characterizable
-        mod_devgem $cmd cohort_scope
-        mod_devgem $cmd falls_back_on
-        mod_devgem $cmd leap
-        mod_devgem $cmd loose_tight_dictionary
-        mod_devgem $cmd sniff
-        mod_devgem $cmd data_miner
-      else
-        mod_devgem $cmd $2
-      fi
-    }
-
-To enable all local gems, run `devgems enable`
-To turn off devgems, run `devgems disable`
-To turn off a specific gem, run `devgems disable leap`
-To turn on a specific gem, run `devgems enable leap`
-
-Typical development process:
-    cd ~
-    git clone http://github.com/rossmeissl/leap.git
-    cd leap
-    <do some development on leap>
-    cd ~/sniff
-    devgems enable leap
-    rake gemspec
-    rm -f Gemfile.lock
-    bundle install
-    <run tests, e.g. `spec spec`>
+Development and testing environment for Brighter Planet emitters.
+
+## Background
+Brighter Planet's emitters, such as [`flight`](http://github.com/brighterplanet/flight), inhabit a complex production runtime environment backing its [emission estimates web service](http://carbon.brighterplanet.com). Sniff simulates this environment, including representative data, fixtures, and other supporting code, so that developers can test improvements to the emitters before submitting them back to Brighter Planet.
+
+### Caution
+The data and other supporting information in the sniff environment is only representative of production data and in many cases is purely fictional, contrived to return predictable results in tests. Emission estimates and other information gleaned from execution within this environment will undoubtedly be--to put it simply--wrong. For real numbers, always use live queries to the [emission estimate web service](http://carbon.brighterplanet.com).
+
+## Usage
+Sniff is never used directly but rather as a requirement of a specific emitter. Current production emitters include, for example:
+
+* [Automobile](http://github.com/brighterplanet/automobile)
+* [Flight](http://github.com/brighterplanet/flight)
+* [Residence](http://github.com/brighterplanet/residence)
+
+For a complete list, see the emission estimate service's [documentation](http://carbon.brighterplanet.com/use).
+
+## The emitter
+An emitter is a software model of a real-world emission source, like a flight. Brighter Planet's emitter libraries each comprise a carbon model, an attribute curation policy, a persistence schema, and a summarization strategy.
+
+### Persistence schema
+Although the production environment does not persist emitter instances, we nevertheless define emitter schemas to enable ActiveRecord assocations. An emitter's schema is defined in `lib/*emitter_name*/data.rb` within an emitter library. For example, here is [flight's schema](http://github.com/brighterplanet/flight/blob/master/lib/flight/data.rb).
+
+Schema are defined using a DSL provided by the [data_miner](http://github.com/seamusabshere/data_miner) library.
+
+### Attribute curation policy
+This defines how an emitter's attributes (initialized and stored with respect to the schema) are curated and decorated into a snapshot for later use by the carbon model. The policy is defined in `lib/*emitter_name*/characterization.rb` within an emitter library. For example, here is [flight's characterization](http://github.com/brighterplanet/flight/blob/master/lib/flight/characterization.rb).
+
+Characterizations are defined using a DSL provided by the [characterizable](http://github.com/seamusabshere/characterizable) library.
+
+### Carbon model
+An emission estimate is obtained by giving an emitter's curated characteristics as input to an execution of its carbon model. The model is defined in `lib/*emitter_name*/characterization.rb` within an emitter library. For example, here is [flight's carbon model](http://github.com/brighterplanet/flight/blob/master/lib/flight/carbon_model.rb).
+
+Carbon models are defined using a DSL provided by the [leap](http://github.com/rossmeissl/leap) library.
+
+### Summarization strategy
+Summaries are human-friendly descriptions of characterized emitters. The strategy is defined in `lib/*emitter_name*/summarization.rb` within an emitter library. For example, here is [flight's summarization strategy](http://github.com/brighterplanet/flight/blob/master/lib/flight/summarization.rb).
+
+Summarizations are defined using a DSL provided by the [summary_judgement](http://github.com/rossmeissl/summary_judgement) library.
+
+## Collaboration cycle 
+Brighter Planet vigorously encourages collaborative improvement of its emitter libraries. Collaboration requires a (free) GitHub account.
+
+### You
+1.  Fork the emitter repository on GitHub.
+1.  Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.
+1.  Improve the code until your new test passes and commit your changes.
+1.  Push your changes to your GitHub fork.
+1.  Submit a pull request to brighterplanet.
+
+### Brighter Planet
+1.  Receive a pull request.
+1.  Pull changes from forked repository.
+1.  Ensure tests pass.
+1.  Review changes for scientific accuracy.
+1.  Merge changes to master repository and publish.
+1.  Direct production environment to use new emitter version.

data/lib/sniff.rb

@@ -9,6 +9,9 @@ module Sniff
     options[:earth] ||= :none
 
     Sniff::Database.init local_root, options
+
+    step_definitions = Dir.glob File.join(File.dirname(__FILE__), 'test_support', 'step_definitions', '**', '*.rb')
+    step_definitions.each { |definition| require definition }
   end
 end
 

data/lib/test_support/step_definitions/carbon_steps.rb

@@ -0,0 +1,63 @@
+require 'time'
+
+Given /^a (.+) (has|used) "(.+)" (of\s?)?"(.*)"$/ do |emitter, _, field, __, value|
+  @emitter_class = emitter.gsub(/\s+/,'_').camelize
+  @emitter_class = "#{@emitter_class}Record".constantize
+  Given "it has \"#{field}\" of \"#{value}\""
+end
+
+Given /^it (has|used) "(.+)" (of\s?)?"(.*)"$/ do |_, field, __, value|
+  @activity_hash ||= {}
+  if value.present?
+    methods = field.split('.')
+    context = @activity_hash
+    methods.each do |method|
+      method = method.to_sym
+      context[method] ||= {}
+      value = Date.parse(value) if value =~ /\d{4}-\d{2}-\d{2}/
+      context[method] = value if method == methods.last.to_sym
+      context = context[method]
+    end
+  end
+end
+
+Given /^the current date is (.+)$/ do |current_date|
+  @current_date = Time.parse(current_date)
+end
+
+When /^emissions are calculated$/ do
+  @activity = @emitter_class.from_params_hash @activity_hash
+  if @current_date
+    Timecop.travel(@current_date) do
+      @emission = @activity.emission Timeframe.this_year
+    end
+  else
+    @emission = @activity.emission Timeframe.this_year
+  end
+  @characteristics = @activity.deliberations[:emission].characteristics
+end
+
+Then /^the emission value should be within (\d+) kgs of (\d+)$/ do |cusion, emissions|
+  @emission.should be_close(emissions.to_f, cusion.to_f)
+end
+
+Then /^the calculation should have used committees (.*)$/ do |committee_list|
+  committees = committee_list.split(/,\s*/)
+  committees.each do |committee|
+    @characteristics.keys.should include(committee)
+  end
+end
+
+Then /^the (.+) committee should be close to ([^,]+), \+\/-(.+)$/ do |committee, value, cusion|
+  @characteristics[committee.to_sym].to_f.should be_close(value.to_f, cusion.to_f)
+end
+
+Then /^the (.+) committee should be exactly (.*)$/ do |committee, value|
+  @characteristics[committee.to_sym].to_s.should == value
+end
+
+Then /^the active_subtimeframe committee should have timeframe (.*)$/ do |tf_string|
+  days, start, finish = tf_string.split(/,\s*/)
+  @characteristics[:active_subtimeframe].to_s.should =~ /#{days} days starting #{start} ending #{finish}/
+end
+

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sniff
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Derek Kastner
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-20 00:00:00 -04:00
+date: 2010-07-22 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -286,82 +286,63 @@ dependencies:
   requirement: *id017
 description: |
   # sniff
-  Testing environment for Brighter Planet Climate Middleware emission calculation gems.
+  Development and testing environment for Brighter Planet emitters.
   
-  This gem provides:
-   * Sample data used for calculations, representative of data found on http://data.brighterplanet.com
-   * A database/ActiveRecord environment for said data
-   * References to gems needed by each emitter gem  
-   * An autoloader that will load any models and sample data needed by the emitter gem being tested (see Usage)
+  ## Background
+  Brighter Planet's emitters, such as [`flight`](http://github.com/brighterplanet/flight), inhabit a complex production runtime environment backing its [emission estimates web service](http://carbon.brighterplanet.com). Sniff simulates this environment, including representative data, fixtures, and other supporting code, so that developers can test improvements to the emitters before submitting them back to Brighter Planet.
   
-  # Usage
-  Within an emitter gem's test setup, you can:
-      require 'sniff'
-      
-      Sniff.init '/path/to/emitter_project'
+  ### Caution
+  The data and other supporting information in the sniff environment is only representative of production data and in many cases is purely fictional, contrived to return predictable results in tests. Emission estimates and other information gleaned from execution within this environment will undoubtedly be--to put it simply--wrong. For real numbers, always use live queries to the [emission estimate web service](http://carbon.brighterplanet.com).
   
-  If an emitter gem has its own test models and data, sniff will look for the models in `EMITTER_GEM_DIR/lib/test_support/data_models/` and the data fixtures in `EMITTER_GEM_DIR/lib/test_support/db/fixtures/`. It will also look for a schema in `EMITTER_GEM_DIR/lib/test_support/db/schema.rb`
+  ## Usage
+  Sniff is never used directly but rather as a requirement of a specific emitter. Current production emitters include, for example:
   
-  # How to contribute
-  Typical contributions will include updates to test data.
+  * [Automobile](http://github.com/brighterplanet/automobile)
+  * [Flight](http://github.com/brighterplanet/flight)
+  * [Residence](http://github.com/brighterplanet/residence)
   
-  1. Fork the project.
-  1. Make your feature addition or bug fix.
-  1. Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-  1. Send me a pull request. Bonus points for topic branches.
+  For a complete list, see the emission estimate service's [documentation](http://carbon.brighterplanet.com/use).
   
-  # Local Gems
-  Sniff depends on several gems, some of which are developed by Brighter Planet.  You can tell Sniff or any of the carbon gems to use your local repos in lieu of installed rubygems through the following steps:
+  ## The emitter
+  An emitter is a software model of a real-world emission source, like a flight. Brighter Planet's emitter libraries each comprise a carbon model, an attribute curation policy, a persistence schema, and a summarization strategy.
   
+  ### Persistence schema
+  Although the production environment does not persist emitter instances, we nevertheless define emitter schemas to enable ActiveRecord assocations. An emitter's schema is defined in `lib/*emitter_name*/data.rb` within an emitter library. For example, here is [flight's schema](http://github.com/brighterplanet/flight/blob/master/lib/flight/data.rb).
   
-  Paste the following functions into your ~/.bash_profile
-      function mod_devgem() {
-        var="LOCAL_`echo $2 | tr 'a-z' 'A-Z'`"
-        
-        if [ "$1" == "disable" ]
-        then
-          echo "unset $var"
-          unset $var
-        else
-          dir=${3:-"~/$2"}
-          echo "export $var=$dir"
-          export $var=$dir
-        fi
-      }
-      
-      function devgems () {
-        # Usage: devgems [enable|disable] [gemname]
-        cmd=${1:-"enable"}
-        if [ -z $2 ]
-        then
-          mod_devgem $cmd characterizable
-          mod_devgem $cmd cohort_scope
-          mod_devgem $cmd falls_back_on
-          mod_devgem $cmd leap
-          mod_devgem $cmd loose_tight_dictionary
-          mod_devgem $cmd sniff
-          mod_devgem $cmd data_miner
-        else
-          mod_devgem $cmd $2
-        fi
-      }
+  Schema are defined using a DSL provided by the [data_miner](http://github.com/seamusabshere/data_miner) library.
   
-  To enable all local gems, run `devgems enable`
-  To turn off devgems, run `devgems disable`
-  To turn off a specific gem, run `devgems disable leap`
-  To turn on a specific gem, run `devgems enable leap`
+  ### Attribute curation policy
+  This defines how an emitter's attributes (initialized and stored with respect to the schema) are curated and decorated into a snapshot for later use by the carbon model. The policy is defined in `lib/*emitter_name*/characterization.rb` within an emitter library. For example, here is [flight's characterization](http://github.com/brighterplanet/flight/blob/master/lib/flight/characterization.rb).
   
-  Typical development process:
-      cd ~
-      git clone http://github.com/rossmeissl/leap.git
-      cd leap
-      <do some development on leap>
-      cd ~/sniff
-      devgems enable leap
-      rake gemspec
-      rm -f Gemfile.lock
-      bundle install
-      <run tests, e.g. `spec spec`>
+  Characterizations are defined using a DSL provided by the [characterizable](http://github.com/seamusabshere/characterizable) library.
+  
+  ### Carbon model
+  An emission estimate is obtained by giving an emitter's curated characteristics as input to an execution of its carbon model. The model is defined in `lib/*emitter_name*/characterization.rb` within an emitter library. For example, here is [flight's carbon model](http://github.com/brighterplanet/flight/blob/master/lib/flight/carbon_model.rb).
+  
+  Carbon models are defined using a DSL provided by the [leap](http://github.com/rossmeissl/leap) library.
+  
+  ### Summarization strategy
+  Summaries are human-friendly descriptions of characterized emitters. The strategy is defined in `lib/*emitter_name*/summarization.rb` within an emitter library. For example, here is [flight's summarization strategy](http://github.com/brighterplanet/flight/blob/master/lib/flight/summarization.rb).
+  
+  Summarizations are defined using a DSL provided by the [summary_judgement](http://github.com/rossmeissl/summary_judgement) library.
+  
+  ## Collaboration cycle 
+  Brighter Planet vigorously encourages collaborative improvement of its emitter libraries. Collaboration requires a (free) GitHub account.
+  
+  ### You
+  1.  Fork the emitter repository on GitHub.
+  1.  Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.
+  1.  Improve the code until your new test passes and commit your changes.
+  1.  Push your changes to your GitHub fork.
+  1.  Submit a pull request to brighterplanet.
+  
+  ### Brighter Planet
+  1.  Receive a pull request.
+  1.  Pull changes from forked repository.
+  1.  Ensure tests pass.
+  1.  Review changes for scientific accuracy.
+  1.  Merge changes to master repository and publish.
+  1.  Direct production environment to use new emitter version.
 
 email: derek.kastner@brighterplanet.com
 executables: []
@@ -386,6 +367,7 @@ files:
 - lib/test_support/db/fixtures/states.csv
 - lib/test_support/db/fixtures/urbanities.csv
 - lib/test_support/db/fixtures/zip_codes.csv
+- lib/test_support/step_definitions/carbon_steps.rb
 - README.markdown
 - spec/lib/sniff/database_spec.rb
 - spec/spec_helper.rb
@@ -426,3 +408,4 @@ summary: Test support for Brighter Planet carbon gems
 test_files: 
 - spec/lib/sniff/database_spec.rb
 - spec/spec_helper.rb
+- lib/test_support/step_definitions/carbon_steps.rb