spreadsheet_agent 0.0.1

data/lib/spreadsheet_agent/error.rb

@@ -0,0 +1,12 @@
+# Author: Darin London
+# The license of this source is "MIT Licence"
+
+module SpreadsheetAgent
+
+# SpreadsheetAgent::Error is an extension of Error that SpreadsheetAgent classes throw
+# when critical errors are encountered
+  class Error < RuntimeError
+  end
+  
+end
+

data/lib/spreadsheet_agent/runner.rb

@@ -0,0 +1,306 @@
+# Author: Darin London
+# The license of this source is "MIT Licence"
+
+require 'spreadsheet_agent/db'
+
+module SpreadsheetAgent
+
+
+# SpreadsheetAgent::Runner is a class designed to facilitate the automated traversal of all, or some
+# defined set of pages, entries, and goals defined in a SpreadsheetAgent compatible Google Spreadsheet,
+# and run agents or processes on them.  By placing a SpreadsheetAgent::Runner script into the scheduling
+# system (cron, etc.) on one or more compute nodes, desired pages, entries, and goals can be processed
+# efficiently over a period of time, and new pages, entries, or goals can be automatically picked up
+# as they are introduced.  Runners can be designed to automate the submission of agent scripts, check
+# the status of jobs, aggregate information about job status, or automate cleanup tasks.
+  class Runner < SpreadsheetAgent::Db
+
+# Boolean. Optional (default false). If true, run will generate the commands that
+# it would run for all runnable entry-goals, print them to STDERR, but not actually
+# run the commands. Automatically sets debug to 1.
+# Note, if the process_entries_with coderef is overridden, dry_run is ignored.
+    attr_accessor :dry_run
+
+# Boolean, Optional (default false). If true, the default process_entries_with PROC
+# runs each agent_script executable in the foreground, rather than in the background,
+# thus in serial. If false, all agent_script executables are run in parallel, in the
+# background.  This is not used when process_entries_with is set to a different PROC.
+    attr_accessor :run_in_serial
+
+# Boolean, Optional (default false). If true, information about pages, entries, and
+# goals that are checked and filtered is printed to STDERR.
+    attr_accessor :debug
+
+# Integer, Optional (default 5). The number of seconds that the runner sleeps between
+# each call to process an entry-goal.
+    attr_accessor :sleep_between
+
+# String Path, Optional.  The path to the directory containing agent executable programs that
+# the default process PROC executes.  The default is the ../agent_bin directory relative
+# to the directory containing the calling script, $0.
+    attr_accessor :agent_bin
+
+# Readonly access to the Hash of key_fields, as defined in :config.  The runner uses this to construct
+# the commandline for each agent on each entry in a page that gets run, with the value of the
+# GoogleDrive::List entry for the given 'key' passed as argument in the order specified by the
+# 'rank' field for each key in the config.
+    attr_reader :query_fields
+
+# Readonly access to the array of pages to be processed.  Only pages will only be defined
+# when :only_pages or :skip_pages are defined in the constructor params, or when the skip_pages_if,
+# or only_pages_if methods are called.
+    attr_reader :only_pages
+    
+    @skip_entry_code = nil
+    @skip_goal_code = nil
+
+# Create a new SpreadsheetAgent::Runner.  Can be created with any of the following optional attributes:
+# * :skip_pages - raises SpreadsheetAgentError if passed along with :only_pages
+# * :only_pages - raises SpreadsheetAgentError if passed along with :skip_pages
+# * :dry_run
+# * :run_in_serial
+# * :debug
+# * :config_file (see SpreadsheetAgent::Db)
+# * :sleep_between
+# * :agent_bin
+#
+    def initialize(attributes = { })
+      if (!attributes[:skip_pages].nil? && !attributes[:only_pages].nil?)
+        raise SpreadsheetAgentError, "You cannot construct a runner with both only_pages and skip_pages"
+      end
+
+      @dry_run = attributes[:dry_run]
+      @run_in_serial = attributes[:run_in_serial]
+      @debug = attributes[:debug]
+      @config_file = attributes[:config_file]
+
+      @sleep_between = 5
+      unless attributes[:sleep_between].nil?
+        @sleep_between = attributes[:sleep_between]
+      end
+    
+      @agent_bin = find_bin() + '../agent_bin'
+      unless attributes[:agent_bin].nil?
+        @agent_bin = attributes[:agent_bin]      
+      end
+
+      if attributes[:skip_pages]
+        @skip_pages = attributes[:skip_pages].clone
+      end
+
+      if attributes[:only_pages]
+        @only_pages = attributes[:only_pages].clone
+      end
+
+      build_db()
+      @query_fields = build_query_fields()
+    
+      if @skip_pages
+        skip_pages_if do |page|
+          @skip_pages.include? page
+        end
+      end
+    
+      if @dry_run
+        @debug = true
+      end
+    end
+
+# Provide a PROC designed to intelligently filter out pages that are not to be processed.
+# If not called, all pages not defined in :only_pages, or :skip_pages parameters in the constructor,
+# or a previous call to only_pages_if will be processed.
+# This will override only_pages, or skip_pages passed as arguments to the constructor, and
+# any previous call to skip_pages_if, or only_pages_if.  The PROC should take the title of
+# a page as a string, and return true if a process decides to skip the page, false otherwise.
+# Must be called before the process! method to affect the pages it processes.  Returns the runner
+# self to facilitate chained processing with skip_goal, skip_entry, and/or process! if desired.
+#
+#   skip pages whose title contains 'skip'
+#   runner.skip_pages_if {|title| title.match(/skip/) }.process!
+#
+#   Same, but without calling process so that skip_entry or skip_goal can be called on the runner
+#   runner.skip_pages_if do |title|
+#     title.match(/skip/)
+#   end
+#   ... can call skip_entry, skip_goal, etc
+#   runner.process!
+#
+    def skip_pages_if(&skip_code)
+      @only_pages = @db.worksheets.collect{ |p| p.title }.reject{ |ptitle| skip_code.call(ptitle) }
+      self
+    end
+
+# Provide a PROC desinged to intelligently determine pages to process. If not called, all pages
+# not affected by the :skip_pages, or :only_pages constructor params, or a previous call to
+# skip_pages_if will be processed.
+# This will override only_pages, or skip_pages passed as arguments to the constructor, and
+# any previous call to skip_pages_if, or only_pages_if.  The PROC should take the title of
+# a page as a string, and return true if a process decides to include the page, false otherwise.
+# Must be called before the process! method to affect the pages it processes.  Returns the runner
+# self to facilitate chained processing with skip_goal, skip_entry, and/or process! if desired.
+#
+#   include only pages whose title begins with 'foo'
+#   runner.only_pages_if {|title| title.match(/^foo/)}.process!
+#
+#   Same, but without calling process so that skip_entry or skip_goal can be called on the runner
+#   runner.only_pages_if do |title|
+#     title.match(/^foo/)
+#   end
+#   ... can call skip_entry, skip_goal
+#   runner.process!
+#
+    def only_pages_if(&include_code)
+      @only_pages = @db.worksheets.collect{ |p| p.title }.select { |ptitle| include_code.call(ptitle) }
+      self
+    end
+
+# Provide a PROC desinged to intelligently determine entries on any page to skip. If not called,
+# all entries on processed pages will be processed.
+# The PROC should take a GoogleDrive::List representing the record in the spreadsheet, which can be accessed
+# as a Hash with fields as key and that fields value as value.  It should return true if the code decides to
+# skip processing the entry, false otherwise.  Must be called before the process! method to affect the entries
+# on each page that it processes.  Returns the runner self to facilitate chained processing with skip_pages_if,
+# only_pages_if, skip_goal, and/or process! if desired.
+#
+#   skip entries which have run foo or bar
+#   runner.only_pages_if {|entry| entry['foo'] == 1 || entry['bar'] == 1 }.process!
+#
+#   skip entries that a human reading the spreadsheet has annotated with less than 3.5 in the 'threshold' field
+#   runner.only_pages_if do |entry|
+#     entry['threshold'] < 3.5
+#   end
+#   ... can call skip_pages_if, only_pages_if, skip_goal
+#   runner.process!
+#
+    def skip_entry(&skip_code)
+      @skip_entry_code = skip_code
+      self
+    end
+
+# Provide a PROC desinged to skip a specific goal in any entry on all pages processed. If not called,
+# all goals of each entry and page to be processed by the runner will be processed.
+#   [note!] Ignored when a PROC is passed to the process! method, e.g. it is only used when process! executes
+#   agent scripts for the goal.
+# The PROC should take a string, which will be one of the header fields in the spreadsheet.  It should return
+# true if that goal is to be skipped, falsed otherwise.
+# Returns the runner self to facilitate chained processing with skip_pages_if, only_pages_if, skip_entry,
+# and/or process! if desired.
+#
+#   skip the 'post_process' goal on each entry of each page processed
+#   runner.skip_goal{|goal| goal == 'post_process' }.process!
+#
+# This is best when used in conjunction with skip_entry to skip_goals for particular entries
+# runner.skip_entry{|entry| entry['threshold'] < 2.5 }.skip_goal{|goal| goal == 'post_process' }.process!
+#
+    def skip_goal(&skip_code)
+      @skip_goal_code = skip_code
+      self
+    end
+
+# Processes configured pages, entries, and goals with a PROC.  The default PROC takes the entry, iterates
+# over each goal not skipped by skip_goal, and:
+# * determines if an executable #{ @agent_bin }/#{ goal }_agent.rb script exists
+# * if so, executes the goal_agent script with commandline arguments constructed from the values in the entry for each field in the query_fields array defined in config.
+# If run_in_serial is false, the default PROC runs each agent in the background, in parallel.
+# Otherwise, it runs each serially in the foreground.  If dry_run is true, the command is printed to STDERR,
+# but is not run.
+# A PROC supplied to override the default PROC should take an GoogleDrive::List, and GoogleDrive::Worksheet as arguments.
+# This allows the process to query the entry for information using its hash access, and/or update the entry on the
+# spreadsheet. In order for changes to the GoogleDrive::List to take effect, the GoogleDrive::Worksheet must be saved in the PROC.
+# The process sleeps @sleep_between between each call to the PROC (default or otherwise).  If dry_run is true
+# when a PROC is supplied, the page.title and runnable_entry hash inspection are printed to STDERR but the PROC
+# is not called.
+#
+#   # call each goal agent script in agent_bin on each entry in each page
+#   runner = SpreadsheetAgent::Runer.new
+#   runner.process!
+#
+#   # find entries with a threshold > 5 and update the 'threshold_exceeded' field
+#   runner.skip_entry{|entry| entry['threshold'] <= 5 }.process! do |entry,page|
+#     entry.update 'threshold_exceeded', "1"
+#     page.save
+#
+#  # only process entries on the 'main' page where the threshold has not been exceeded
+#  runner.only_pages = ['main']
+#  runner.skip_entry{|entry| entry['threshold'] != 1 }.process!
+#
+    def process!(&runner_code)
+      get_runnable_entries().each do |entry_info|
+        entry_page, runnable_entry = entry_info
+        if runner_code.nil?
+          default_process(runnable_entry)
+        elsif @dry_run
+          $stderr.print "Would run #{ entry_page.title } #{ runnable_entry.inspect }"
+        else
+          runner_code.call(runnable_entry, entry_page)
+        end
+        sleep @sleep_between
+      end
+    end
+
+    private
+
+    def get_runnable_entries
+      runnable_entries = []
+      get_pages_to_process().each do |page|
+        $stderr.puts "Processing page " + page.title if @debug
+        runnable_entries += page.list.reject { |check_entry |  @skip_entry_code.nil? ? false : @skip_entry_code.call(check_entry)  }.collect{ |entry| [page, entry] }
+      end
+
+      return runnable_entries
+    end
+
+    def run_entry_goal(entry, goal)
+      $stderr.puts "Running goal #{goal}" if @debug
+
+      goal_agent = [@agent_bin, "#{ goal }_agent.rb"].join('/')
+      cmd = [goal_agent]
+
+      @query_fields.each do |query_field|
+        if entry[query_field]
+          cmd.push entry[query_field]
+        end
+      end
+
+      command = cmd.join(' ')
+      command += '&' unless @run_in_serial
+      $stderr.puts command if @debug
+      if File.executable?(goal_agent)
+        unless @dry_run
+          system(command)
+        end
+      else
+        $stderr.puts "AGENT RUNNER DOES NOT EXIST!" if @debug
+      end
+    end
+
+    def default_process(runnable_entry)
+      title = query_fields.collect { |field| runnable_entry[field] }.join(' ')
+      $stderr.puts "Checking goals for #{ title }" if @debug
+
+      runnable_entry.keys.reject { |key|
+        if @skip_goal_code.nil?
+          false
+        else
+          ( @skip_goal_code.call(key) )
+        end
+      }.each do |goal|
+        run_entry_goal(runnable_entry, goal)
+        sleep @sleep_between
+      end
+    end
+  
+    def build_query_fields
+      @config['key_fields'].keys.sort { |a,b| @config['key_fields'][a]['rank'] <=> @config['key_fields'][b]['rank'] }
+    end
+
+    def get_pages_to_process
+      if @only_pages.nil?
+        @db.worksheets
+      else
+        @db.worksheets.select { |page|  @only_pages.include? page.title }
+      end
+    end
+  end #Runner
+end #SpreadsheetAgent
+

data/test/agent_bin/othergoal_agent.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+$:.unshift( File.expand_path( File.dirname(__FILE__) + '/../../lib' ) )
+require 'spreadsheet_agent'
+
+page, entry = ARGV
+
+google_agent = SpreadsheetAgent::Agent.new({
+                                      :agent_name => File.basename($0).sub('_agent.rb',''),
+                                      :config_file => File.expand_path( File.dirname(__FILE__) + '/../../config/agent.conf.yml' ),
+                                      :page_name => page,
+                                      :keys => { 'testentry' => entry, 'testpage' => page }
+                                    })
+
+google_agent.process! do |entry|
+  true
+end
+exit

data/test/agent_bin/testgoal_agent.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+$:.unshift( File.expand_path( File.dirname(__FILE__) + '/../../lib' ) )
+require 'spreadsheet_agent'
+
+page, entry = ARGV
+
+google_agent = SpreadsheetAgent::Agent.new({
+                                      :agent_name => File.basename($0).sub('_agent.rb',''),
+                                      :config_file => File.expand_path( File.dirname(__FILE__) + '/../../config/agent.conf.yml' ),
+                                      :page_name => page,
+                                      :keys => { 'testentry' => entry, 'testpage' => page }
+                                    })
+
+google_agent.process! do |entry|
+  true
+end
+exit

data/test/spreadsheet_agent_db_test.rb

@@ -0,0 +1,13 @@
+require 'test/unit'
+require 'spreadsheet_agent/db'
+
+class TC_SpreadsheetAgentDbTest < Test::Unit::TestCase
+  def test_instantiate_db
+    conf_file = File.expand_path(File.dirname( __FILE__ )) + '/../config/agent.conf.yml'
+    assert File.exists?( conf_file ), "You must create a valid test Google Spreadsheet and a valid #{ conf_file } configuration file pointing to it to run the tests. See README.txt file for more information on how to run the tests."
+
+    google_db = SpreadsheetAgent::Db.new()
+    assert_not_nil google_db
+    assert_instance_of(SpreadsheetAgent::Db, google_db)
+  end
+end #TC_SpreadsheetAgentDbTest

data/test/spreadsheet_agent_runner_test.rb

@@ -0,0 +1,468 @@
+require 'test/unit'
+require 'shoulda/context'
+require 'spreadsheet_agent'
+require 'spreadsheet_agent/runner'
+require 'capture_io'
+
+class TC_SpreadsheetAgentRunnerTest < Test::Unit::TestCase
+
+  context 'Runner' do
+
+    setup do
+      @config_file = File.expand_path(File.dirname( __FILE__ )) + '/../config/agent.conf.yml'
+
+      unless File.exists? @config_file
+        $stderr.puts "You must create a valid test Google Spreadsheet and a valid #{ @config_file } configuration file pointing to it to run the tests. See README.txt file for more information on how to run the tests."
+        exit(1)
+      end
+      @test_agent_bin = find_bin() + 'agent_bin'
+      @testing_pages = nil
+      @agent_scripts = nil
+    end
+
+    teardown do
+      runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :config_file => @config_file)
+      if runner.db.worksheet_by_title('testing').nil?
+        tpage = runner.db.add_worksheet('testing')
+        tpage.max_rows = 2
+        tpage.save
+      end
+      unless @testing_pages.nil?
+        @testing_pages.each do |testing_page|
+          testing_page.delete
+        end
+      end
+      agent_scripts_executable(false)
+    end
+
+    context 'instantiated' do
+
+     should 'be a SpreadsheetAgent::Runner' do
+        runner = SpreadsheetAgent::Runner.new(:config_file => @config_file)
+        assert_not_nil runner, 'runner is nil!'
+        assert_instance_of(SpreadsheetAgent::Runner, runner)
+      end
+
+    end #instantiated
+
+    context 'agent_bin' do
+
+      should 'have a sensible default' do
+        expected_agent_bin = File.expand_path(File.dirname( $0 )) + '/../agent_bin'
+        runner = SpreadsheetAgent::Runner.new(:config_file => @config_file)
+        assert_equal expected_agent_bin, runner.agent_bin
+      end
+
+      should 'be overridable on construction' do
+        runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :config_file => @config_file)
+        assert_equal @test_agent_bin, runner.agent_bin
+      end
+
+    end #agent_bin
+
+    context 'agent scripts' do
+
+      setup do
+        @entries = {'dotest' => false, 'donottest' => false }
+        @headers = ['testentry', 'testpage', 'ready', 'testgoal', 'othergoal', 'complete']
+        @runner = prepare_runner(
+                                 ['foo_page', 'bar_page'],
+                                 @headers,
+                                 @entries
+                                 )
+      end
+
+      should 'pass tests' do
+        #should 'not run if scripts in agent_bin are not executable' do
+        reset_testing_pages(@testing_pages,true)
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal 1, entry[2].to_i
+          end
+        end
+        agent_scripts_executable(false)
+          
+        Dir.glob("#{  @test_agent_bin }/*.rb") do |rb_file|
+          assert !File.executable?(rb_file), "#{ rb_file } should not be executable"
+        end
+        
+        @runner.process!
+
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert entry[3].nil? || entry[3].empty?, "entry #{ entry[0] } should not have run!: #{ entry.inspect }"
+            assert entry[4].nil? || entry[3].empty?, "entry #{ entry[0] } should not have run!: #{ entry.inspect }"
+          end
+        end
+
+        #should not run on entries that are not ready
+        reset_testing_pages(@testing_pages)
+        agent_scripts_executable(true)
+        @testing_pages.each do |page|
+          page.rows(1).each do |entry|
+            assert entry[2].to_i != 1, "entry #{ entry[0] } should not be ready!: #{ entry.inspect }"
+          end
+        end
+        
+        @runner.process!
+        sleep 2
+
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert entry[3].to_i != 1, "entry #{ entry[0] } should not have run!: #{ entry.inspect }"
+          end
+        end
+
+        # should 'if executable, run for each goal of each ready entry by default' do
+        reset_testing_pages(@testing_pages,true)
+        
+        @runner.process!
+        sleep 5
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[4]
+          end
+        end
+
+        # should 'allow code to be passed to override default process! function' do
+        reset_testing_pages(@testing_pages, true)
+        expected_to_run = {}
+        @testing_pages.each do |page|
+          expected_to_run[page.title] = {}
+          (2..page.num_rows).to_a.each do |rownum|
+            expected_to_run[page.title][page[rownum,1]] = false
+          end
+          page.save
+        end
+        
+        @runner.process! do |ran_entry, ran_page|
+          ran_entry.update 'testgoal' => "1"
+          ran_page.save
+          expected_to_run[ran_page.title][ran_entry['testentry']] = true
+        end
+        sleep 2
+        
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[2]
+            assert_equal "1", entry[3]
+            assert expected_to_run[page.title][entry[0]], "#{ page.title } should have been processed on #{ entry[0] }"
+          end
+        end
+
+        # should 'allow code passed to override default process! function to update fields on each entry' do
+        reset_testing_pages(@testing_pages, true)
+
+        @runner.process! do |ran_entry, ran_page|
+          ran_entry.update 'complete' => "1"
+          ran_page.save
+        end
+        sleep 2
+        
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[5]
+          end
+        end
+
+        # should 'not print anything to STDERR if debug is not set to true' do
+        reset_testing_pages(@testing_pages, true)
+
+        nothing_output = CaptureIO.new
+        nothing_output.start
+        @runner.process! do |re, rp|
+          re.update 'othergoal' => "1"
+          rp.save
+        end
+        nothing_captured = nothing_output.stop
+        assert nothing_captured[:stderr].length < 1, 'should not have captured any stderr'
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[4]
+          end
+        end
+
+        # should 'allow debug to be set and print output to STDERR' do
+        reset_testing_pages(@testing_pages, true)
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :debug => true, :config_file => @config_file)
+        assert @runner.debug, 'debug should be true'
+        debug_output = CaptureIO.new
+        debug_output.start
+        @runner.process! do |re, rp|
+          re.update 'testgoal' => "1"
+          rp.save
+        end
+        debugged_output = debug_output.stop
+        assert debugged_output[:stderr].length > 0, "should have captured stderr in debug mode"
+        sleep 2        
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[3]
+          end
+        end
+
+        # should 'allow dry_run to be set, and not run any entries, but set debug to true' do
+        reset_testing_pages(@testing_pages, true)
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :dry_run => true, :config_file => @config_file)
+        assert @runner.debug, 'debug should be true with dry run'
+
+        dry_output = CaptureIO.new
+        dry_output.start
+        @runner.process! do |re, rp|
+          re.update 'testgoal' => "1"
+          rp.save
+        end
+        captured_dry_output = dry_output.stop
+        assert captured_dry_output[:stderr].length > 0, 'should have captured stderr in debug mode'
+        sleep 2
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert entry[3].nil? || entry[3].empty?, "#{ page.title } should not have run #{ entry[0] } #{ entry.inspect }"
+          end
+        end
+
+        # should 'allow sleep_between to be set, and sleep that amount between process for each entry' do
+        reset_testing_pages(@testing_pages, true)
+        expected_time_between = 10
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :sleep_between => expected_time_between,:config_file => @config_file)
+
+        beginning_time = Time.now
+        first_time = true
+        @runner.process! do |re, rp|
+          if first_time
+            first_time = false
+          else
+            elapsed_time = Time.now - beginning_time
+            assert_equal expected_time_between, elapsed_time.to_i
+          end
+          re.update 'testgoal' => "1"
+          rp.save
+          beginning_time = Time.now          
+        end
+        sleep 2
+        
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[3]
+          end
+        end
+
+        #should 'allow skip_entry to be set with code, and only process entries that return false from the code when passed the entry' do
+        reset_testing_pages(@testing_pages, true)
+
+        @runner.skip_entry do |entry|
+          (entry['testentry'] == 'donottest')
+        end
+
+        @runner.process! do |ran_entry, ran_page|
+          ran_entry.update 'testgoal' => "1"
+          ran_page.save
+        end
+        sleep 2        
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            if entry[0] == 'donottest'
+              assert entry[3].nil? || entry[3].empty?, "#{  page.title } #{ entry[0]} should not have run"
+            else
+              assert_equal "1", entry[3]
+            end
+          end
+        end
+
+        # should 'allow skip_goal to be set with code, and only process goals for each entry that return false from the code when passed the goal' do
+        reset_testing_pages(@testing_pages, true)
+
+        @runner.skip_goal { |goal|
+          if goal == 'othergoal'
+            return true
+          else
+            return false
+          end
+        }.process!
+        sleep 2
+        @testing_pages.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert entry[3] == "1", "entry #{ entry[0] } should have run testgoal #{ entry.inspect }"
+            assert entry[4].nil? || entry[4].empty?, "othergoal should not have run for any entry #{ entry.inspect }"
+          end
+        end
+
+        #should 'allow only_pages to be set and only process @only_pages' do
+        @test_only_pages = ['foo_page', 'baz_page']
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :only_pages => @test_only_pages, :config_file => @config_file)
+        @testing_pages.push(add_page_to_runner(@runner, 'baz', @headers, @entries))
+
+
+        expected_to_run = {}
+        @testing_pages.each do |page|
+          expected_to_run[page.title] = @test_only_pages.include? page.title
+        end
+        
+        @runner.process! do |ran_entry, ran_page|
+          ran_entry.update 'complete' => "1"
+          ran_page.save
+          assert expected_to_run[ran_page.title], "#{ ran_page.title } is not in #{ @test_only_pages.inspect }!"
+        end
+        
+        @testing_pages.select { |page| @test_only_pages.include? page.title }.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[5]
+          end
+        end
+
+        #should 'allow only_pages_if to be set and only process those pages' do
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin,:config_file => @config_file)
+        reset_testing_pages(@testing_pages, true)
+        
+        @runner.only_pages_if{ |title|
+          if title.match('ba*')
+            return true
+          else
+            return false
+          end
+        }.process! do |ran_entry, ran_page|
+          ran_entry.update 'complete' => "1"
+          ran_page.save
+          assert ran_page.title.match('ba*'), "#{ ran_page.title } was not expected to run!"
+        end
+        
+        @testing_pages.select { |page| page.title.match('ba*') }.each do |page|
+         page.reload 
+         page.rows(1).each do |entry|
+            assert_equal "1", entry[5]
+          end
+        end
+
+        #should 'allow skip_pages to be set and only process pages not in @skip_pages' do
+        @test_skip_pages = ['foo_page', 'baz_page']
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin, :skip_pages => @test_skip_pages,:config_file => @config_file)
+        reset_testing_pages(@testing_pages, true)
+        expected_to_run = {}
+        @testing_pages.each do |page|
+          expected_to_run[page.title] = !( @test_skip_pages.include? page.title )
+        end
+        
+        @runner.process! do |ran_entry, ran_page|
+          ran_entry.update 'complete' => "1"
+          ran_page.save
+          assert expected_to_run[ran_page.title], "#{ ran_page.title } is in #{ @test_skip_pages.inspect }!"
+        end
+        
+        @testing_pages.each do |page|
+          page.reload
+          if @test_skip_pages.include?(page.title)
+            should_equal = nil
+          else
+            should_equal = "1"
+          end
+          page.rows(1).each do |entry|
+            assert_equal should_equal, entry[4]
+          end
+        end
+
+        #should 'allow skip_pages_if to be set and only process pages not skipped by the code' do
+        @runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin,:config_file => @config_file)
+        reset_testing_pages(@testing_pages, true)
+        
+        @runner.skip_pages_if { |title|
+          title.match('ba*')
+        }.process! do |ran_entry, ran_page|
+          ran_entry.update 'complete' => "1"
+          ran_page.save
+          assert !( ran_page.title.match('ba*') ), "#{ ran_page.title } was not expected to run!"
+        end
+        
+        @testing_pages.reject { |page| page.title.match('ba*') }.each do |page|
+          page.reload
+          page.rows(1).each do |entry|
+            assert_equal "1", entry[5]
+          end
+        end
+
+      end #pass tests
+
+    end #agent script executable
+
+  end #Runner
+
+  def find_bin()
+    File.expand_path(File.dirname( __FILE__ )) + '/'
+  end
+
+  def prepare_runner(pages, headers, entries)
+    runner = SpreadsheetAgent::Runner.new(:agent_bin => @test_agent_bin,:config_file => @config_file)
+    @testing_pages = []
+    
+    pages.each do |page|
+      @testing_pages.push(add_page_to_runner(runner, page, headers, entries))
+    end
+    testing_page = runner.db.worksheet_by_title('testing')
+    unless testing_page.nil?
+      testing_page.delete
+    end
+
+    runner
+  end
+
+  def add_page_to_runner(runner, page, headers, entries)
+    testing_page = runner.db.worksheet_by_title(page)
+      if testing_page.nil?
+        testing_page = runner.db.add_worksheet(page)
+      else
+        testing_page.max_rows = 1
+      end
+      
+      colnum = 1
+      headers.each do |field|
+        testing_page[1,colnum] = field
+        colnum += 1
+      end
+      entry_row = 2
+      entries.each do |entry, ready|
+        testing_page[entry_row,1] = entry
+        testing_page[entry_row,2] = page
+        testing_page[entry_row,3] = "1" if ready
+        entry_row += 1
+        
+      end
+      testing_page.max_rows = entry_row
+      testing_page.save
+      testing_page
+  end
+
+  def agent_scripts_executable(set_executable)
+    if set_executable
+      `chmod 700 #{  @test_agent_bin }/*.rb`
+    else
+      `chmod 600 #{  @test_agent_bin }/*.rb`
+    end
+  end
+
+  def reset_testing_pages(testing_pages, ready = false)
+    ready_value = ready ? "1" : nil
+
+    testing_pages.each do |page|
+      (2..page.num_rows).to_a.each do |rownum|
+        page[rownum,3] = ready_value
+        page[rownum,4] = nil
+        page[rownum,5] = nil
+        page[rownum,6] = nil
+      end
+      page.save
+    end
+  end
+
+end #TC_SpreadsheetAgentRunnerTest