terminus 0.2.0 → 0.3.0

data/README.rdoc

@@ -1,112 +1,50 @@
 = Terminus
 
-* http://github.com/jcoglan/terminus
+* http://terminus.jcoglan.com
 
 Terminus is an experimental Capybara driver implemented in client-side
-JavaScript. It lets you script your application in any browser on any
-device, without needing browser plugins. This allows several types of
-testing to be automated:
+JavaScript. It lets you script your application in any browser on any device,
+without needing browser plugins. This allows several types of testing to be
+automated:
 
 * Cross-browser testing
 * Multi-browser interaction e.g. messaging apps
-* Run tests on remote machines, phones, iPads etc.
-
-It is also a remote scripting tool, giving you a REPL that lets you
-run JavaScript in any number of browsers at once.
-
-
-== Usage
-
-Terminus is a Capybara driver. For the most part, you will not use
-it directly: you will use the Capybara API and it will send instructions
-to Terminus for execution. To set Terminus as your driver:
-
-  require 'capybara'
-  require 'terminus'
-  
-  Capybara.current_driver = :terminus
-
-Terminus does require some extra setup before you can use it to control
-your app. First up, you need to start the Terminus server on the machine
-where your application will be running:
-
-  $ terminus
-
-This starts the server on port 7004. Now open a browser at
-http://127.0.0.1:7004/. (I recommend using the IP address of the Terminus
-host; Chrome has bugs that can stop WebSockets working if you use the
-hostname.) This is the 'holding page'. A browser is said to be 'docked'
-while it is visiting this page, meaning it is ready and waiting to run
-some tests for you.
-
-To let Terminus control your app's pages, you need to include this
-just before the closing +body+ tag when in testing mode:
-
-  <!-- For example if you're using Rails -->
-  
-  <% if Rails.env.test? %>
-    <%= Terminus.driver_script '127.0.0.1' %>
-  <% end %>
-
-If the browser you're using is on a different machine to the Terminus
-server, replace <tt>127.0.0.1</tt> with the Terminus machine's IP as
-seen by the browser. For example if I'm running the browser in VirtualBox
-and the Terminus server on the host OS, then I set the IP to <tt>10.0.2.2</tt>.
-You could also use <tt>request.host</tt> to get the right IP automatically
-if you're running your app and your Terminus server on the same machine.
-
-Finally, in your tests you need to make sure there's a docked browser
-and select it. In a 'before' block, run the following:
-
-  Terminus.ensure_docked_browser
-  Terminus.browser = :docked
-
-After each test is finished, you need to return the browser to the
-holding page to make it ready to accept new work. In an 'after' block:
-
-  Terminus.return_to_dock
-
-This returns all currently connected browsers to the holding page.
+* Testing on remote machines, phones, iPads etc.
 
 
 == Notes / to-do
 
-* Support IE, which has no built-in XPath engine for querying the DOM.
-  I'm working on Pathology (see http://github.com/jcoglan/pathology) to
-  try and fix this but it's currently not fast enough.
-  
-* Allow <tt>Terminus.browser=</tt> to select browsers by name and
-  version so we can control multiple browsers at once.
+* Support IE, which has no built-in XPath engine for querying the DOM. I'm
+  working on Pathology (see http://github.com/jcoglan/pathology) to try and fix
+  this but it's currently not fast enough.
   
-* It's slow, especially at filling out forms. Use it to sanity-check
-  your cross-browser code and JavaScript, not to test your whole app.
+* It's slow, especially at filling out forms. Use it to sanity-check your
+  cross-browser code and JavaScript, not to test your whole app.
   
-* It can be a little brittle, and occasionally there seem to be race
-  conditions when running the Capybara specs.
+* It can be a little brittle, and occasionally there seem to be race conditions
+  when running the Capybara specs.
 
 
 == License
 
 (The MIT License)
 
-Copyright (c) 2010 James Coglan
+Copyright (c) 2010-2011 James Coglan
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the 'Software'), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 

data/bin/terminus

@@ -5,7 +5,7 @@ require 'oyster'
 require File.expand_path(File.dirname(__FILE__) + '/../lib/terminus')
 
 spec = Oyster.spec do
-  name "terminus -- controll web browsers from the command line"
+  name "terminus -- Control web browsers with Ruby"
   synopsis "terminus [--port PORT]"
   
   integer :port, :default => Terminus::DEFAULT_PORT
@@ -15,30 +15,14 @@ begin
   options = spec.parse
   app = Terminus.create(options)
   
-  app.run!
-  puts "Terminus server running on port #{options[:port]}"
-  puts "Press CTRL-C to exit"
-  puts ""
-  
   trap("INT") { app.stop! ; exit }
   
-  begin
-    require 'readline'
-    
-    puts "This is the Terminus console. You can type JavaScript"
-    puts "in here and it will be executed on all connected pages."
-    puts ""
-    
-    loop {
-      script, result = Readline.readline('>> '), nil
-      Readline::HISTORY.push(script)
-      app.execute(script) { |r| result = r }
-    }
-  rescue LoadError
-    puts "If you install the readline library, you'll get a console"
-    puts "that lets you execute JavaScript in connected browsers."
-    puts ""
-  end
+  Terminus.port = options[:port]
+  
+  puts "Terminus server running on port #{Terminus.port}"
+  puts "Press CTRL-C to exit"
+  puts ""
+  app.run!
   
 rescue Oyster::HelpRendered
 end

data/lib/capybara/driver/terminus.rb

@@ -1,30 +1,49 @@
-require 'forwardable'
-
 class Capybara::Driver::Terminus < Capybara::Driver::Base
-  def initialize(app = nil)
+  attr_reader :options
+  
+  def initialize(app = nil, options = {})
     raise ArgumentError.new if app.nil?
-    @app = app
+    
+    @app         = Terminus::Proxy[app]
+    @options     = options
     @rack_server = Capybara::Server.new(@app)
-    @rack_server.boot if Capybara.run_server
+    
+    @rack_server.boot
+  end
+  
+  def find(xpath)
+    browser.find(xpath, self)
   end
   
   def visit(path)
-    browser.visit @rack_server.url(path)
+    browser.visit(@rack_server.url(path))
   end
   
   extend Forwardable
   def_delegators :browser, :body,
-                           :current_path,
                            :current_url,
                            :evaluate_script,
                            :execute_script,
-                           :find,
                            :reset!,
-                           :source
+                           :response_headers,
+                           :source,
+                           :status_code
   
   def within_window(name)
     current_browser = browser
-    Terminus.browser = {:name => name}
+    Terminus.browser = browser.id + '/' + name
+    yield
+    Terminus.browser = current_browser
+  end
+  
+  def within_frame(name)
+    frame_src = browser.frame_src(name)
+    frame = browser.frames.find do |frame|
+      frame.current_url == frame_src or
+      frame.current_path == frame_src
+    end
+    current_browser = browser
+    Terminus.browser = frame
     yield
     Terminus.browser = current_browser
   end
@@ -32,7 +51,7 @@ class Capybara::Driver::Terminus < Capybara::Driver::Base
 private
   
   def browser
-    Terminus.ensure_browser
+    Terminus.ensure_browsers
     Terminus.browser
   end
 end

data/lib/terminus.rb

@@ -1,38 +1,39 @@
 require 'forwardable'
 require 'uri'
-require 'rubygems'
 require 'rack'
 require 'thin'
 require 'eventmachine'
 require 'faye'
-require 'capybara'
 require 'sinatra'
 require 'packr'
-
-root = File.expand_path(File.dirname(__FILE__))
-
-%w[ application
-    server
-    timeouts
-    controller
-    browser
-    node
-
-].each do |file|
-  require File.join(root, 'terminus', file)
-end
-
-require root + '/capybara/driver/terminus'
+require 'capybara'
+require 'rack-proxy'
+require 'useragent'
 
 Thin::Logging.silent = true
 
 module Terminus
-  VERSION      = '0.2.0'
   FAYE_MOUNT   = '/messaging'
   DEFAULT_HOST = 'localhost'
   DEFAULT_PORT = 7004
+  LOCALHOST    = /^(localhost|0\.0\.0\.0|127\.0\.0\.1)$/
+  RETRY_LIMIT  = 3
+  
+  ROOT = File.expand_path(File.dirname(__FILE__))
+  autoload :Application, ROOT + '/terminus/application'
+  autoload :Browser,     ROOT + '/terminus/browser'
+  autoload :Controller,  ROOT + '/terminus/controller'
+  autoload :Host,        ROOT + '/terminus/host'
+  autoload :Node,        ROOT + '/terminus/node'
+  autoload :Proxy,       ROOT + '/terminus/proxy'
+  autoload :Server,      ROOT + '/terminus/server'
+  autoload :Timeouts,    ROOT + '/terminus/timeouts'
+  
+  require ROOT + '/capybara/driver/terminus'
   
   class << self
+    attr_accessor :debug
+    
     def create(options = {})
       Server.new(options)
     end
@@ -42,7 +43,7 @@ module Terminus
     end
     
     def endpoint(host = DEFAULT_HOST)
-      "http://#{host}:#{DEFAULT_PORT}#{FAYE_MOUNT}"
+      "http://#{host}:#{port}#{FAYE_MOUNT}"
     end
     
     def ensure_reactor_running
@@ -50,12 +51,22 @@ module Terminus
       while not EM.reactor_running?; end
     end
     
+    def port
+      @port || DEFAULT_PORT
+    end
+    
+    def port=(port)
+      @port = port.to_i
+    end
+    
     extend Forwardable
     def_delegators :controller, :browser,
+                                :browsers,
                                 :browser=,
-                                :ensure_docked_browser,
-                                :ensure_browser,
-                                :return_to_dock
+                                :ensure_browsers,
+                                :return_to_dock,
+                                :rewrite_local,
+                                :rewrite_remote
     
   private
     

data/lib/terminus/application.rb

@@ -4,16 +4,16 @@ module Terminus
     ROOT = File.expand_path(File.dirname(__FILE__) + '/../')
     
     set :static, true
-    set :public, ROOT + '/public'
-    set :views,  ROOT + '/views'
+    set :public, ROOT + '/terminus/public'
+    set :views,  ROOT + '/terminus/views'
     
     def self.driver_script(host)
-      %Q{<script type="text/javascript" src="http://#{host}:#{DEFAULT_PORT}/controller.js"></script>}
+      %Q{<script type="text/javascript" src="http://#{host}:#{Terminus.port}/bootstrap.js"></script>}
     end
     
     helpers do
-      def bookmarklet
-        Packr.pack(erb(:bookmarklet), :shrink_vars => true)
+      def bootstrap
+        Packr.pack(erb(:bootstrap), :shrink_vars => true)
       end
       
       def host
@@ -21,8 +21,14 @@ module Terminus
       end
     end
     
-    get('/') { erb :index }
-    get('/controller.js') { bookmarklet }
+    get '/' do
+      erb :index
+    end
+    
+    get '/bootstrap.js' do
+      headers 'Content-Type' => 'text/javascript'
+      bootstrap
+    end
     
   end
 end

data/lib/terminus/browser.rb

@@ -3,19 +3,36 @@ module Terminus
     
     include Timeouts
     
-    LOCALHOST   = /localhost|0\.0\.0\.0|127\.0\.0\.1/
-    RETRY_LIMIT = 3
+    extend Forwardable
+    def_delegator  :@user_agent, :browser, :name
+    def_delegators :@user_agent, :os, :version
     
     def initialize(controller)
-      @controller     = controller
-      @attributes     = {}
-      @docked         = false
-      @namespace      = Faye::Namespace.new
-      @ping_callbacks = []
-      @results        = {}
+      @controller = controller
+      @attributes = {}
+      @docked     = false
+      @frames     = Set.new
+      @namespace  = Faye::Namespace.new
+      @results    = {}
+      
       add_timeout(:dead, Timeouts::TIMEOUT) { drop_dead! }
     end
     
+    def ===(params)
+      return docked? if params == :docked
+      return params == id if String === params
+      return false if @parent
+      return false unless @user_agent
+      
+      params.all? do |name, value|
+        property = __send__(name).to_s
+        case value
+        when Regexp then property =~ value
+        when String then property == value
+        end
+      end
+    end
+    
     def ask(command, retries = RETRY_LIMIT)
       id = tell(command)
       result_hash = wait_with_timeout(:result) { result(id) }
@@ -29,17 +46,13 @@ module Terminus
       ask([:body])
     end
     
-    def source
-      ask([:source])
-    end
-    
     def current_path
       return nil unless url = @attributes['url']
       URI.parse(url).path
     end
     
     def current_url
-      @attributes['url']
+      @attributes['url'] || ''
     end
     
     def docked?
@@ -55,32 +68,67 @@ module Terminus
       nil
     end
     
-    def find(xpath)
-      ask([:find, xpath, false]).map { |id| Node.new(self, id) }
+    def find(xpath, driver = nil)
+      ask([:find, xpath, false]).map { |id| Node.new(self, id, driver) }
+    end
+    
+    def frame!(frame_browser)
+      @frames.add(frame_browser)
+    end
+    
+    def frames
+      @frames.to_a
+    end
+    
+    def frame_src(name)
+      ask([:frame_src, name])
     end
     
     def id
       @attributes['id']
     end
-    alias :name :id
     
     def page_id
       @attributes['page']
     end
     
     def ping!(message)
+      p message if Terminus.debug
       remove_timeout(:dead)
       add_timeout(:dead, Timeouts::TIMEOUT) { drop_dead! }
+      
+      uri = @controller.rewrite_local(message['url'], @dock_host)
+      message['url'] = uri.to_s
+      
       @attributes = @attributes.merge(message)
+      @user_agent = UserAgent.parse(message['ua'])
       detect_dock_host
+      
+      @infinite_redirect = message['infinite']
+      
+      if parent = message['parent']
+        @parent = Terminus.browser(parent)
+        @parent.frame!(self) unless @parent == self
+      end
+      
       @ping = true
     end
     
     def reset!
-      ask([:reset])
+      if url = @attributes['url']
+        uri = URI.parse(url)
+        visit("http://#{uri.host}:#{uri.port}")
+      end
+      ask([:clear_cookies])
+      @attributes.delete('url')
+    end
+    
+    def response_headers
+      evaluate_script('TERMINUS_HEADERS')
     end
     
     def result!(message)
+      p message if Terminus.debug
       @results[message['commandId']] = message['result']
     end
     
@@ -90,19 +138,36 @@ module Terminus
     end
     
     def return_to_dock
-      visit "http://#{@controller.dock_host}:#{DEFAULT_PORT}/"
+      visit "http://#{@dock_host}:#{Terminus.port}/"
+    end
+    
+    def source
+      evaluate_script('TERMINUS_SOURCE')
+    end
+    
+    def status_code
+      evaluate_script('TERMINUS_STATUS')
     end
     
     def tell(command)
       id = @namespace.generate
+      p [id, command] if Terminus.debug
       messenger.publish(channel, 'command' => command, 'commandId' => id)
       id
     end
     
     def visit(url, retries = RETRY_LIMIT)
-      url = url.gsub(LOCALHOST, @controller.dock_host)
-      tell([:visit, url])
+      close_frames!
+      uri = @controller.rewrite_remote(url, @dock_host)
+      uri.host = @dock_host if uri.host =~ LOCALHOST
+      tell([:visit, uri.to_s])
       wait_for_ping
+      
+      if @infinite_redirect
+        @infinite_redirect = nil
+        raise Capybara::InfiniteRedirectError
+      end
+      
     rescue Timeouts::TimeoutError => e
       raise e if retries.zero?
       visit(url, retries - 1)
@@ -113,22 +178,39 @@ module Terminus
       wait_with_timeout(:ping) { @ping or @dead }
     end
     
+    def to_s
+      "<#{self.class.name} #{name} #{version} (#{os})>"
+    end
+    alias :inspect :to_s
+    
+  protected
+    
+    def drop_dead!
+      remove_timeout(:dead)
+      close_frames!
+      @dead = true
+      @controller.drop_browser(self)
+    end
+    
   private
     
     def channel
       "/terminus/clients/#{id}"
     end
     
-    def detect_dock_host
-      uri = URI.parse(@attributes['url'])
-      return unless uri.port == DEFAULT_PORT
-      @docked = true
-      @controller.dock_host = uri.host
+    def close_frames!
+      @frames.each { |frame| frame.drop_dead! }
+      @frames = Set.new
     end
     
-    def drop_dead!
-      @dead = true
-      @controller.drop_browser(self)
+    def detect_dock_host
+      uri = URI.parse(@attributes['url'])
+      if uri.port == Terminus.port
+        @docked = true
+        @dock_host = uri.host
+      else
+        @docked = false
+      end
     end
     
     def messenger