asautotest 0.0.1

data/README.rdoc

@@ -0,0 +1,182 @@
+= ASAutotest
+
+ASAutotest is an automatic compilation and testing tool ideally suited
+for non-IDE ActionScript development.
+
+It operates by watching your entire source directory, triggering a
+recompilation as soon as any source file changes.  Compilation errors
+are reported to the terminal in a nice way.  To keep compilation times
+to a minimum, it uses the Flex Compiler Shell (FCSH).
+
+There is also support for automatically running tests after a
+successful compilation, but this currently requires some manual glue,
+is undocumented and a bit hard to set up (once set up, though, it
+works really well).  For a working example of the kind of glue you
+need, see <tt><test-project/src/specification.as></tt>.
+
+
+== Installation
+
+The easiest way to install ASAutotest is via Rubygems:
+
+  $ sudo gem install asautotest
+
+You can also install ASAutotest by simply symlinking the executables
+into your PATH:
+
+  $ ln -s ~/asautotest/bin/asautotest ~/bin
+  $ ln -s ~/asautotest/bin/flash-policy-server ~/bin
+
+To get started, you need fcsh, which is part of the Flex SDK.
+It should either be in your PATH, or you can set the <tt>FCSH</tt>
+environment variable to the location of the <tt>fcsh</tt> executable.
+(Unfortunately, symlinking <tt>fcsh</tt> into your PATH may not work;
+if so, you will likely end up preferring to set the
+environment variable.)
+
+You can find the Flex SDK here:
+http://opensource.adobe.com/wiki/display/flexsdk
+
+
+== Usage
+
+Once you have both <tt>asautotest</tt> and <tt>fcsh</tt> in place, try
+this:
+
+  $ asautotest ~/my-project/src/main.as
+
+This will compile <tt>main.as</tt>, using <tt>~/my-project/src</tt> as
+the source directory, and then go to sleep, waiting for changes.
+As soon as some <tt>*.as</tt> or <tt>*.mxml</tt> file in
+<tt>~/my-project/src</tt> (or any subdirectory) changes, ASAutotest
+will wake up and perform a recompilation.
+
+By default, the resulting SWF is placed in a temporary directory and
+then thrown away.  If you want to use the SWF, you need to specify
+where it should be placed, using the <tt>--output</tt> option (or
+<tt>-o</tt> for short):
+
+  $ cd ~/my-project
+  $ asautotest src/main.as -o bin/my-project.swf
+
+If you have additional source directores, add them using the
+<tt>--source</tt> option (or <tt>-I</tt> for short):
+
+  $ asautotest ~/my-project/src/main.as -I ~/my-other-project/src
+
+To link with SWC files, use the <tt>--library</tt> option (or
+<tt>-l</tt> for short):
+
+  $ asautotest main.as -l ../lib/some-library.swc
+
+
+== Autotesting
+
+You can tell ASAutotest to run your SWF as a test using the
+<tt>--test</tt> option (or <tt>-t</tt> for short):
+
+  $ asautotest spec.as --test
+
+For this to work, your test must follow a rather complicated protocol
+involving connecting to a socket and sending the test results in a
+specific (non-standard) format.  ASAutotest comes with adapter code
+for ASSpec, so if your tests are written using ASSpec, then getting up
+and running with autotesting should be easy.  
+
+Your <tt>foo_spec.as</tt> should look like this:
+
+  package
+  {
+    import asautotest.ASSpecRunner
+  
+    public class foo_spec extends ASSpecRunner
+    {
+      public function foo_spec()
+      { super(new FooSuite) }
+    }
+  }
+
+Then you need to add <tt>asautotest/assspec/src</tt> as a source
+directory:
+
+  $ asautotest foo_spec.as --test -l asspec.swc -I ~/asautotest/asspec/src
+
+Because the test communicates with ASAutotest through a socket, you
+also need to run a Flash cross-domain policy server on port 843 (which
+unfortunately requires root privileges); otherwise, the test will not
+be able to connect to ASAutotest:
+
+  $ sudo flash-policy-server
+
+This will just keep running, so you may want to start it in a screen:
+
+  $ screen sudo flash-policy-server
+
+You should be all set for autotesting now.  Try it out by changing
+something in your code and watching the tests run automatically.
+Note that the tests are only executed if all compilations succeed.
+
+
+=== Advanced autotesting
+
+By default, ASAutotest expects the test to connect to port 50102.
+If for some reason you need to use a different port (maybe you have
+multiple ASAutotest instances running at the same time), you can use
+the <tt>--test-port</tt> option to specify it:
+
+  $ asautotest foo_spec.as --test --test-port 54321
+
+To change the port that the ASSpec adapter connects to, do this:
+
+      public function foo_spec()
+      { super(new FooSuite, 54321) }
+
+If you need to write your own adapter to another testing framework,
+you can use <tt>ASSpecRunner.as</tt> as a starting point.
+
+
+== Multi-compilation
+
+If you need to compile multiple SWFs (for example, one production SWF
+and one test), use <tt>--</tt> (double hyphen) to divide the command
+line into sections:
+
+  $ asautotest foo.as -o foo.swf -- foo_spec.as --test
+
+This works with any number of source files:
+
+  $ asautotest foo.as -- bar.as -- baz.as -- quux.as
+
+Options specified in such a section only apply to that source file.
+In the following example, only <tt>bar.as</tt> is linked with
+<tt>asspec.swc</tt> and compiled to <tt>bar.swf</tt>; the other two
+files are just compiled to check for errors.
+
+  $ asautotest foo.as -- bar.as -o bar.swf -l asspec.swc -- baz.as
+
+You can use <tt>---</tt> (triple hyphen) to specify global options:
+
+  $ asautotest foo.as -o foo.swf -- foo_spec.as --test --- -l asspec.swc
+
+In the above example, both <tt>foo.as</tt> and <tt>foo_spec.as</tt>
+would be linked with <tt>asspec.swc</tt>.
+
+
+== License
+
+Copyright (C) 2010, 2011  Go Interactive <http://gointeractive.se/>
+
+This file is part of ASAutotest.
+
+ASAutotest is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+ASAutotest is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with ASAutotest.  If not, see <http://www.gnu.org/licenses/>.

data/bin/asautotest

@@ -0,0 +1,437 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+# asautotest --- automatically compile and test ActionScript code
+# Copyright (C) 2010, 2011  Go Interactive
+
+# This file is part of ASAutotest.
+
+# ASAutotest is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# ASAutotest is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with ASAutotest.  If not, see <http://www.gnu.org/licenses/>.
+
+require "rubygems"
+require "pathname"
+require "tmpdir"
+
+module ASAutotest
+  current_directory = File.dirname(Pathname.new(__FILE__).realpath)
+  ROOT = File.expand_path(File.join(current_directory, ".."))
+end
+
+$: << File.join(ASAutotest::ROOT, "lib")
+
+ENV["ASAUTOTEST_ROOT"] = ASAutotest::ROOT
+
+require "asautotest/compilation-output-parser"
+require "asautotest/compilation-result"
+require "asautotest/compilation-runner"
+require "asautotest/compiler-shell"
+require "asautotest/logging"
+require "asautotest/problematic-file"
+require "asautotest/stopwatch"
+require "asautotest/test-runner"
+require "asautotest/utilities"
+
+module ASAutotest
+  FCSH = ENV["FCSH"] || "fcsh"
+  FLASHPLAYER = ENV["FLASHPLAYER"] || "flashplayer"
+  WATCH_GLOB = "**/[^.]*.{as,mxml}"
+  DEFAULT_TEST_PORT = 50102
+  GROWL_ERROR_TOKEN = "ASAutotest-#{ARGV.inspect.hash}"
+
+  class << self
+    attr_accessor :growl_enabled
+    attr_accessor :displaying_growl_error
+  end
+
+  class CompilationRequest
+    attr_reader :source_file_name
+    attr_reader :source_directories
+    attr_reader :library_file_names
+    attr_reader :test_port
+    attr_reader :output_file_name
+    attr_reader :extra_mxmlc_options
+
+    def production? ; @production end
+    def test? ; @test end
+    def temporary_output? ; @temporary_output end
+
+    def initialize(options)
+      @source_file_name = options[:source_file_name]
+      @source_directories = options[:source_directories]
+      @library_file_names = options[:library_file_names]
+      @production = options[:production?]
+      @test = options[:test?]
+      @test_port = options[:test_port] || DEFAULT_TEST_PORT
+      @extra_mxmlc_options = options[:extra_mxmlc_options] || []
+
+      if options.include? :output_file_name
+        @output_file_name = File.expand_path(options[:output_file_name])
+      else
+        @output_file_name = get_temporary_output_file_name
+        @temporary_output = true
+      end
+    end
+
+    def get_temporary_output_file_name
+      "#{Dir.tmpdir}/asautotest-#{get_random_token}.swf"
+    end
+
+    def get_random_token
+      "#{(Time.new.to_f * 1000).to_i}-#{(rand * 1_000_000).to_i}"
+    end
+
+    def compilation_command
+      if @compile_id
+        %{compile #@compile_id}
+      else
+        build_string do |result|
+          result << %{mxmlc}
+          for source_directory in @source_directories do
+            result << %{ -compiler.source-path=#{source_directory}}
+          end
+          for library in @library_file_names do
+            result << %{ -compiler.library-path=#{library}}
+          end
+          result << %{ -output=#@output_file_name}
+          result << %{ -static-link-runtime-shared-libraries}
+          result << %{ -compiler.strict}
+          result << %{ -debug} unless @production
+          for option in @extra_mxmlc_options
+            result << %{ #{option}}
+          end
+          result << %{ #@source_file_name}
+        end
+      end
+    end
+
+    attr_accessor :compile_id
+    attr_accessor :index
+  end
+
+  class Main
+    include Logging
+
+    def initialize(options)
+      initialize_growl if options[:enable_growl?]
+      @typing = options[:typing]
+      @compilation_requests = options[:compilation_requests].
+        map(&method(:make_compilation_request))
+    end
+
+    def initialize_growl
+      begin
+        require "growl"
+        if Growl.installed?
+          ASAutotest::growl_enabled = true
+        else
+          shout "You need to install the ‘growlnotify’ tool."
+          say "Alternatively, use --no-growl to disable Growl notifications."
+          exit -1
+        end
+      rescue LoadError
+        hint "Hint: Install the ‘growl’ gem to enable Growl notifications."
+      end
+    end
+
+    def make_compilation_request(options)
+      options[:source_file_name] =
+        File.expand_path(options[:source_file_name])
+      implicit_source_directory =
+        File.dirname(File.expand_path(options[:source_file_name])) + "/"
+      options[:source_directories] = options[:source_directories].
+        map { |directory_name| File.expand_path(directory_name) + "/" }
+      options[:source_directories] << implicit_source_directory unless
+        options[:source_directories].include? implicit_source_directory
+      options[:library_file_names] = options[:library_file_names].
+        map { |file_name| File.expand_path(file_name) }
+
+      CompilationRequest.new(options)
+    end
+
+    def self.run(*arguments)
+      new(*arguments).run
+    end
+
+    def run
+      print_header
+      start_compiler_shell
+      build
+      monitor_changes
+    end
+
+    def say_tabbed(left, right)
+      say("#{left} ".ljust(21) + right)
+    end
+
+    def format_file_name(file_name)
+      if file_name.start_with? ENV["HOME"]
+        file_name.sub(ENV["HOME"], "~")
+      else
+        file_name
+      end
+    end
+
+    def print_header
+      new_logging_section
+
+      for request in @compilation_requests
+        say "\e[1m#{File.basename(request.source_file_name)}\e[0m"
+        
+        for source_directory in request.source_directories
+          say_tabbed "  Source directory:",
+            format_file_name(source_directory)
+        end
+        
+        for library in request.library_file_names
+          say_tabbed "  Library:", format_file_name(library)
+        end
+
+        unless request.extra_mxmlc_options.empty?
+          say_tabbed "  Extra options:", request.extra_mxmlc_options * " "
+        end          
+
+        if request.temporary_output? and not request.test?
+          say "  Not saving output SWF (use --output=FILE.swf to specify)."
+          say "  Not running as test (use --test to enable)."
+        elsif not request.temporary_output?
+          say_tabbed "  Output file:",
+            "=> #{format_file_name(request.output_file_name)}"
+        elsif request.test?
+          say "  Running as test (using port #{request.test_port})."
+        end
+
+        say "  Compiling in production mode." if request.production?
+      end
+
+      say "Running in verbose mode." if Logging.verbose?
+
+      if @typing == :dynamic
+        say "Not warning about missing type declarations."
+      end
+
+      new_logging_section
+    end
+
+    def start_compiler_shell
+      @compiler_shell = CompilerShell.new \
+        :compilation_requests => @compilation_requests,
+        :typing => @typing
+      @compiler_shell.start
+    end
+
+    def monitor_changes
+      user_wants_out = false
+
+      Signal.trap("INT") do
+        user_wants_out = true
+        throw :asautotest_interrupt
+      end
+      
+      until user_wants_out
+        require "fssm"
+        monitor = FSSM::Monitor.new
+
+        for source_directory in source_directories
+          monitor.path(source_directory, WATCH_GLOB) do |watch|
+            watch.update { handle_change }
+            watch.create { handle_change ; throw :asautotest_interrupt }
+            watch.delete { handle_change ; throw :asautotest_interrupt }
+          end
+        end
+
+        catch :asautotest_interrupt do
+          begin
+            monitor.run
+          rescue
+          end
+        end
+      end
+    end
+
+    def source_directories
+      @compilation_requests.map(&:source_directories).flatten.uniq
+    end
+
+    def handle_change
+      new_logging_section
+      whisper "Change detected."
+      build
+    end
+
+    def build
+      compile
+
+      for summary in @compilation.result.summaries
+        if summary[:successful?]
+          if compilation_successful? and summary[:request].test?
+            run_test(summary[:request])
+          end
+
+          if summary[:request].temporary_output?
+            delete_output_file(summary[:request].output_file_name)
+          end
+        end
+      end
+
+      whisper "Ready."
+    end
+
+    def compilation_successful?
+      @compilation.result.successful?
+    end
+
+    def n_problems
+      @compilation.result.n_problems
+    end
+
+    def n_problematic_files
+      @compilation.result.n_problematic_files
+    end
+
+    def compile
+      @compilation = CompilationRunner.new \
+        @compiler_shell, :typing => @typing
+      @compilation.run
+    end
+
+    def run_test(request)
+      TestRunner.new(request.output_file_name, request.test_port).run
+    end
+
+    def delete_output_file(file_name)
+      begin
+        File.delete(file_name)
+        whisper "Deleted binary."
+      rescue Exception => exception
+        shout "Failed to delete binary: #{exception.message}"
+      end
+    end
+  end
+end
+
+def print_usage
+  warn "\
+usage: asautotest FILE.as [--test|-o FILE.swf] [-I SRCDIR|-l FILE.swc]...
+       asautotest FILE.as [OPTION] [-- FILE.as [OPTION]]... [--- OPTIONS...]"
+end
+
+def new_compilation_request
+  { :source_directories => [], :library_file_names => [], :extra_mxmlc_options => [] }
+end
+
+$compilation_requests = [new_compilation_request]
+$typing = nil
+$verbose = false
+$enable_growl = RUBY_PLATFORM =~ /darwin/
+$parsing_global_options = false
+
+until ARGV.empty?
+  request = $compilation_requests.last
+  requests = $parsing_global_options ? $compilation_requests : [request]
+  case argument = ARGV.shift
+  when /^--output(?:=(\S+))?$/, "-o"
+    if request.include? :output_file_name
+      warn "asautotest: only one ‘--output’ allowed per source file"
+      warn "asautotest: use ‘--’ to separate multiple source files"
+      print_usage ; exit -1
+    else
+      request[:output_file_name] = ($1 || ARGV.shift)
+    end
+  when "--production"
+    for request in requests
+      request[:production?] = true
+    end
+  when "--test"
+    if $parsing_global_options
+      warn "asautotest: option ‘--test’ cannot be used globally"
+      print_usage ; exit -1
+    else
+      request[:test?] = true
+    end
+  when "--test-port(?:=(\S+))?"
+    value = ($1 || ARGV.shift).to_i
+    for request in requests
+      request[:test_port] = value
+    end
+  when /^--library(?:=(\S+))?$/, "-l"
+    value = ($1 || ARGV.shift)
+    for request in requests
+      request[:library_file_names] << value
+    end
+  when /^--source=(?:=(\S+))?$/, "-I"
+    value = ($1 || ARGV.shift)
+    for request in requests
+      request[:source_directories] << value
+    end
+  when /^--asspec-adapter-source$/
+    value = File.join(ASAutotest::ROOT, "asspec", "src")
+    for request in requests
+      request[:source_directories] << value
+    end
+  when "--dynamic-typing"
+    $typing = :dynamic
+  when "--static-typing"
+    $typing = :static
+  when "--verbose"
+    $verbose = true
+  when "--no-growl"
+    $enable_growl = false
+  when /^--mxmlc-option(?:=(.*))?$/, "-X"
+    value = ($1 || ARGV.shift)
+    for request in requests
+      request[:extra_mxmlc_options] << value
+    end
+  when "--"
+    if request.include? :source_file_name
+      $compilation_requests << new_compilation_request
+    else
+      warn "asautotest: no source file found before ‘--’"
+      print_usage ; exit -1
+    end
+  when "---"
+    if $parsing_global_options
+      warn "asautotest: only one ‘---’ section allowed"
+      print_usage ; exit -1
+    else
+      $parsing_global_options = true
+    end
+  when /^-/
+    warn "asautotest: unrecognized argument: #{argument}"
+    print_usage ; exit -1
+  else
+    if request.include? :source_file_name
+      warn "asautotest: use ‘--’ to separate multiple source files"
+      print_usage ; exit -1
+    else
+      request[:source_file_name] = argument
+    end
+  end
+end
+
+unless $compilation_requests.first[:source_file_name]
+  warn "asautotest: please specify a source file to be compiled"
+  print_usage ; exit -1
+end
+
+ASAutotest::Logging.verbose = $verbose
+
+begin
+  ASAutotest::Main.run \
+    :compilation_requests => $compilation_requests,
+    :typing => $typing,
+    :enable_growl? => $enable_growl
+rescue Interrupt
+end
+
+# Signal successful exit.
+exit 200