Class: Autotest

Class | Autotest
In: | lib/autotest.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

add_discovery add_exception add_hook add_mapping add_sigint_handler all_good autodiscover clear_exceptions clear_mappings consolidate_failures exceptions files_matching find_files find_files_to_test get_to_green handle_results hook known_files make_test_cmd new new_hash_of_arrays path_to_classname remove_exception remove_mapping reorder rerun_all_tests reset ruby run run run_tests test_files_for wait_for_changes

### Classes and Modules

Module Autotest::AutoUpdate
Module Autotest::Once
Module Autotest::RCov
Module Autotest::Restart
Module Autotest::Timestamp

### Constants

T0 | = | Time.at 0
ALL_HOOKS | = | [ :all_good, :died, :green, :initialize, :interrupt, :quit, :ran_command, :red, :reset, :run_command, :updated, :waiting ]
HOOKS | = | Hash.new { |h,k| h[k] = [] }
WINDOZE | = | /win32/ =~ RUBY_PLATFORM
SEP | = | WINDOZE ? '&' : ';'

### 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] |
libs | [RW] |
order | [RW] |
output | [RW] |
results | [RW] |
sleep | [RW] |
tainted | [RW] |
testlib | [RW] |
unit_diff | [RW] |
wants_to_quit | [RW] |

### Public Class methods

add_discovery(&proc)

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

add_hook(name, &block)

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

autodiscover()

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

new()

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

run()

Initialize and run the system.

### Public Instance methods

add_exception(regexp)

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

add_mapping(regexp, prepend = false, &proc)

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

add_sigint_handler()

Installs a sigint handler.

all_good()

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

clear_exceptions()

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

clear_mappings()

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.

consolidate_failures(failed)

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

exceptions()

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

files_matching(regexp)

Returns all known files in the codebase matching `regexp`.

find_files()

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

find_files_to_test(files=find_files)

Find the files which have been modified, update the recorded timestamps, and use this to update the files to test. Returns true if any file is newer than the previously recorded most recent file.

get_to_green()

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

handle_results(results)

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

hook(name, *args)

Call the event hook named `name`, executing all registered hooks until one returns true. Returns false if no hook handled the event.

known_files()

Lazy accessor for the known_files hash.

make_test_cmd(files_to_test)

Generate the commands to test the supplied files

new_hash_of_arrays()
path_to_classname(s)

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

remove_exception(regexp)

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

remove_mapping(regexp)

Removed a file mapping matching `regexp`.

reorder(files_to_test)
rerun_all_tests()

Rerun the tests from cold (reset state)

reset()

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

ruby()

Determine and return the path of the ruby executable.

run()

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

run_tests()

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

test_files_for(filename)

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.

wait_for_changes()

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

[Validate]