Torkify

Torkify aims to be a one-stop shop for testing ruby applications, and handling callbacks after test execution for things like notifications.

Torkify integrates with tork, which is a solution for automating test execution, as you change your source files.

Torkify hooks in to tork's remote events, and allows you to add gems and build callbacks that run when tests fail or pass. This makes it easy for you to write code that triggers cool stuff when your tests explode (your imagination is the limit).

Plus, tork is a fantastic tool that makes it very easy to run tests immediately and automatically in a pre-loaded environment.

An example

You define callbacks by creating an observer that defines certain methods. Here's an example that creates a system notification:

# my_tork_notifier.rb
require 'torkify'

class SystemNotifier
  def notify(text)
    # Do a system call to fire a popup notification, e.g. `notify-send`
  end

  def on_pass(event)
    notify "Test passed: #{event.file}"
  end

  def on_fail(event)
    notify "Test failed: #{event.file}, log file #{event.log_file}"
  end
end

listener = Torkify.listener
listener.add_observer SystemNotifier.new
listener.start

This connects to an existing tork process that's running in the current directory.

Usage

Create a ruby script, load torkify and set up a new listener:

# my_tork_notifier.rb

require 'torkify'

listener = Torkify.listener

This listener allows you to add observer objects which you create yourself:

# my_tork_notifier.rb

listener.add_observer MyObserver.new
listener.start  # connect to tork and pass all events to the observer(s)

Observer callback methods

Your observer classes can define any number of the following methods:

on_startup: when torkify starts
on_shutdown: when torkify shuts down
on_test: when a test is started
on_pass: when a test passes
on_fail: when a test fails
on_pass_now_fail: when a previously passed test fails
on_fail_now_pass: when a previously failed test passes
on_absorb: when tork re-absorbs the environment

Each method takes an optional event object as a parameter: this contains all the contextual information about that event. See callback event objects below for a complete list of accessible attributes on the events.

Options for starting torkify

Calling start() on the listener will try and attach to a running tork process in the same directory as the script is run. This starts the process tork-remote tork-engine in the current directory. If you want to change the command that's called (e.g. if bundler is giving you grief), then you can pass that as the first parameter to start:

# my_tork_notifier.rb

listener.start 'bundle exec tork-remote tork-engine'  # Will use this command instead

If tork is running in a different directory, you can pass in a path as the second parameter:

# my_tork_notifier.rb

listener.start 'tork-remote tork-engine', '/home/user/project'

start() will assume that tork is running, and will exit if no tork process is found. If you want it to keep looping until tork starts, use start_loop():

# my_tork_notifier.rb

listener.start_loop   # you can pass the same parameters as with start()

Starting with tork

You may not want to keep tork and torkify separate - for convenience, torkify allows you to start both at the same time. It forks torkify as a child process and runs tork in the parent, allowing you to interact with tork via STDIN but giving you the callbacks of torkify. Just use start_with_tork():

# my_tork_notifier.rb

listener.start_with_tork 'bundle exec tork', 'default:logdir'   # Starts both tork and torkify

Both parameters are optional. The first is the command to execute tork, and the second is the $TORK_CONFIGS environment variable.

Multiple observers

You can add multiple observers to your listener:

require 'torkify'

class FirstObserver
  #...
end

class SecondObserver
  #...
end

listener.Torkify.listener
listener.add_observer FirstObserver.new
listener.add_observer SecondObserver.new
listener.start

Callback event objects

Here's an example observer, and the accessible data on the events provided in the callbacks:


class MyObserver
  def on_test(event)
    event.type      #=> "test"
    event.file      #=> "spec/example_spec.rb"
    event.log_file  #=> "spec/example_spec.rb.log"
    event.lines     #=> [10, 11, 12]
    event.worker    #=> 0
  end

  def on_pass(event)
    event.type      #=> "pass"
    event.file      #=> "spec/example_spec.rb"
    event.log_file  #=> "spec/example_spec.rb.log"
    event.lines     #=> [10, 11, 12]
    event.worker    #=> 0
    event.exit_code #=> 0
    event.pid       #=> 22813
  end

  def on_fail(event)
    event.type      #=> "fail"
    event.file      #=> "spec/example_spec.rb"
    event.log_file  #=> "spec/example_spec.rb.log"
    event.lines     #=> [10, 11, 12]
    event.worker    #=> 0
    event.exit_code #=> 0
    event.pid       #=> 22813
  end

  # The event has an inner event, which is the same type of event
  # that's passed to #on_fail()
  def on_pass_now_fail(event)
    event.type       #=> "pass_now_fail"
    event.file       #=> "spec/example_spec.rb"
    event.event.type #=> "fail"
  end

  # The event has an inner event, which is the same type of event
  # that's passed to #on_pass()
  def on_fail_now_pass(event)
    event.type       #=> "fail_now_pass"
    event.file       #=> "spec/example_spec.rb"
    event.event.type #=> "pass"
  end

  def on_absorb(event)
    event.type      #=> "absorb"
  end

  def on_startup(event)
    event.type      #=> "startup"
  end

  def on_shutdown(event)
    event.type      #=> "shutdown"
  end
end

Installation

Add this line to your application's Gemfile:

gem 'torkify'

And then execute:

$ bundle

Or install it yourself as:

$ gem install torkify

Usage

TODO: Write usage instructions here

Contributing

The guidelines are:

The tests must pass (run python vdebugtests.py in the top directory of the plugin)
Your commit messages should follow the rules outlined here

The steps are:

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request