Class Autotest
In: lib/autotest.rb
lib/autotest/preload.rb
Parent: Object

Autotest continuously scans the files in your project for changes and runs the appropriate tests. Test failures are run until they have all passed. Then the full test suite is run to ensure that nothing else was inadvertantly broken.

If you want Autotest to start over from the top, hit ^C once. If you want Autotest to quit, hit ^C twice.

Rails:

The autotest command will automatically discover a Rails directory by looking for config/environment.rb. When Rails is discovered, autotest uses RailsAutotest to perform file mappings and other work. See RailsAutotest for details.

Plugins:

Plugins are available by creating a .autotest file either in your project root or in your home directory. You can then write event handlers in the form of:

  Autotest.add_hook hook_name { |autotest| ... }

The available hooks are listed in ALL_HOOKS.

See example_dot_autotest.rb for more details.

If a hook returns a true value, it signals to autotest that the hook was handled and should not continue executing hooks.

Naming:

Autotest uses a simple naming scheme to figure out how to map implementation files to test files following the Test::Unit naming scheme.

  • Test files must be stored in test/
  • Test files names must start with test_
  • Test class names must start with Test
  • Implementation files must be stored in lib/
  • Implementation files must match up with a test file named test_.*implementation.rb

Strategy:

  1. Find all files and associate them from impl <-> test.
  2. Run all tests.
  3. Scan for failures.
  4. Detect changes in ANY (ruby?. file, rerun all failures + changed files.
  5. Until 0 defects, goto 3.
  6. When 0 defects, goto 2.

Methods

Classes and Modules

Module Autotest::AutoUpdate
Module Autotest::Bundler
Module Autotest::Isolate
Module Autotest::Once
Module Autotest::Preload
Module Autotest::RCov
Module Autotest::Restart
Module Autotest::Timestamp

Constants

RUBY19 = defined? Encoding
T0 = Time.at 0
ALL_HOOKS = [ :all_good, :died, :green, :initialize, :post_initialize, :interrupt, :quit, :ran_command, :red, :reset, :run_command, :updated, :waiting ]
HOOKS = Hash.new { |h,k| h[k] = [] }
WINDOZE = /mswin|mingw/ =~ RbConfig::CONFIG['host_os']
SEP = WINDOZE ? '&' : ';'

External Aliases

tainted -> tainted?

Attributes

completed_re  [RW] 
extra_class_map  [RW] 
extra_files  [RW] 
failed_results_re  [RW] 
files_to_test  [RW] 
find_directories  [RW] 
find_order  [RW] 
interrupted  [RW] 
known_files  [W] 
last_mtime  [RW] 
latest_results  [RW] 
libs  [RW] 
order  [RW] 
output  [RW] 
prefix  [RW] 
results  [RW] 
sleep  [RW] 
tainted  [RW] 
testlib  [RW] 
unit_diff  [RW] 
wants_to_quit  [RW] 

Public Class methods

Add a proc to the collection of discovery procs. See autodiscover.

Add the supplied block to the available hooks, with the given name.

Automatically find all potential autotest runner styles by searching your loadpath, vendor/plugins, and rubygems for "autotest/discover.rb". If found, that file is loaded and it should register discovery procs with autotest using add_discovery. That proc should return one or more strings describing the user‘s current environment. Those styles are then combined to dynamically invoke an autotest plugin to suite your environment. That plugin should define a subclass of Autotest with a corresponding name.

Process:

  1. All autotest/discover.rb files loaded.
  2. Those procs determine your styles (eg ["rails", "rspec"]).
  3. Require file by sorting styles and joining (eg ‘autotest/rails_rspec’).
  4. Invoke run method on appropriate class (eg Autotest::RailsRspec.run).

Example autotest/discover.rb:

  Autotest.add_discovery do
    "rails" if File.exist? 'config/environment.rb'
  end

Initialize the instance and then load the user‘s .autotest file, if any.

Initialize and run the system.

Calculates the autotest runner to use to run the tests.

Can be overridden with —style, otherwise uses ::autodiscover.

Public Instance methods

Adds regexp to the list of exceptions for find_file. This must be called before the exceptions are compiled.

Adds a file mapping, optionally prepending the mapping to the front of the list if prepend is true. regexp should match a file path in the codebase. proc is passed a matched filename and Regexp.last_match. proc should return an array of tests to run.

For example, if test_helper.rb is modified, rerun all tests:

  at.add_mapping(/test_helper.rb/) do |f, _|
    at.files_matching(/^test.*rb$/)
  end

Installs a sigint handler.

Installs a sigquit handler

If there are no files left to test (because they‘ve all passed), then all is good.

Clears the list of exceptions for find_file. This must be called before the exceptions are compiled.

Clears all file mappings. This is DANGEROUS as it entirely disables autotest. You must add at least one file mapping that does a good job of rerunning appropriate tests.

Returns a hash mapping a file name to the known failures for that file.

Return a compiled regexp of exceptions for find_files or nil if no filtering should take place. This regexp is generated from exception_list.

Returns all known files in the codebase matching regexp.

Find the files to process, ignoring temporary files, source configuration management files, etc., and return a Hash mapping filename to modification time.

Find the files which have been modified, update the recorded timestamps, and use this to update the files to test. Returns the latest mtime of the files modified or nil when nothing was modified.

Keep running the tests after a change, until all pass.

Check results for failures, set the "bar" to red or green, and if there are failures record this.

Call the event hook named name, passing in optional args depending on the hook itself.

Returns false if no hook handled the event.

Hook Writers!

This executes all registered hooks until one returns truthy. Pay attention to the return value of your block!

Lazy accessor for the known_files hash.

Generate the commands to test the supplied files

old_run_tests()

Alias for run_tests

Convert a path in a string, s, into a class name, changing underscores to CamelCase, etc.

Removes regexp to the list of exceptions for find_file. This must be called before the exceptions are compiled.

Removed a file mapping matching regexp.

Rerun the tests from cold (reset state)

Clear all state information about test failures and whether interrupts will kill autotest.

Determine and return the path of the ruby executable.

Returns the base of the ruby command.

Repeatedly run failed tests, then all tests, then wait for changes and carry on until killed.

Look for files to test then run the tests and handle the results.

Return the name of the file with the tests for filename by finding a test_mapping that matches the file and executing the mapping‘s proc.

Sleep then look for files to test, until there are some.

[Validate]