headless 0.1.0 → 0.2.1

data/.gitignore

@@ -0,0 +1,3 @@
+.bundle
+Gemfile.lock
+pkg/*

data/CHANGELOG

@@ -1,3 +1,8 @@
-## 0.1.0
+## 0.2.1 (2011-08-26)
+* added ability to capture screenshots (from https://github.com/iafonov/headless)
+* added ability to capture video (from https://github.com/iafonov/headless)
+* fixed issue with stray pidfile
+
+## 0.1.0 (2010-08-15)
 * introduced options
 * make it possible to change virtual screen dimensions and pixel depth

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in ci_util.gemspec
+gemspec

data/README.md

@@ -1,10 +1,13 @@
 # Headless
 
 Headless is a Ruby interface for Xvfb. It allows you to create a headless display straight from Ruby code, hiding some low-level action.
+It can also capture images and video from the virtual framebuffer.
 
 I created it so I can run Selenium tests in Cucumber without any shell scripting. Even more, you can go headless only when you run tests against Selenium.
 Other possible uses include pdf generation with `wkhtmltopdf`, or screenshotting.
 
+Documentation is available at [rdoc.info](http://rdoc.info/projects/leonid-shevtsov/headless)
+
 ## Installation
 
 On Debian/Ubuntu:
@@ -52,12 +55,37 @@ Running cucumber headless is now as simple as adding a before and after hook in
 
       headless = Headless.new
       headless.start
+    end
+
+## Capturing video
+
+Video is captured using `ffmpeg`. You can install it on Debian/Ubuntu via `sudo apt-get install ffmpeg` or on OS X via `brew install ffmpeg`. You can capture video continuously or capture scenarios separately. Here is typical use case:
 
-      at_exit do
-        headless.destroy
+    require 'headless'
+
+    headless = Headless.new
+    headless.start
+
+    Before do
+      headless.video.start_capture
+    end
+
+    After do |scenario|
+      if scenario.failed?
+        headless.video.stop_and_save("/tmp/#{BUILD_ID}/#{scenario.name.split.join("_")}.mov")
+      else
+        headless.video.stop_and_discard
       end
     end
 
+## Taking screenshots
+
+Images are captured using `import` utility which is part of `imagemagick` library. You can install it on Ubuntu via `sudo apt-get install imagemagick`. You can call `headless.take_screenshot` at any time. You have to supply full path to target file. File format is determined by supplied file extension.
+
+## Contributors
+
+* [Igor Afonov](http://iafonov.github.com) - video and screenshot capturing functionality.
+
 ---
 
-© 2010 Leonid Shevtsov, released under the MIT license
+© 2011 Leonid Shevtsov, released under the MIT license

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/headless.gemspec

@@ -0,0 +1,18 @@
+spec = Gem::Specification.new do |s|
+  s.author = 'Leonid Shevtsov'
+  s.email = 'leonid@shevtsov.me'
+
+  s.name = 'headless'
+  s.version = '0.2.1'
+  s.summary = 'Ruby headless display interface'
+
+  s.description = <<-EOF
+    Headless is a Ruby interface for Xvfb. It allows you to create a headless display straight from Ruby code, hiding some low-level action.
+  EOF
+  s.requirements = 'Xvfb'
+  s.homepage = 'http://leonid.shevtsov.me/en/headless'
+
+  s.files         = `git ls-files`.split("\n")
+
+  s.add_development_dependency "rspec", "~> 2.6"
+end

data/lib/headless.rb

@@ -1,3 +1,6 @@
+require 'headless/cli_util'
+require 'headless/video/video_recorder'
+
 # A class incapsulating the creation and usage of a headless X server
 #
 # == Prerequisites
@@ -38,7 +41,7 @@
 #++
 class Headless
 
-  class Exception < ::Exception
+  class Exception < RuntimeError
   end
 
   # The display number
@@ -53,29 +56,31 @@ class Headless
   # * +display+ (default 99) - what display number to listen to;
   # * +reuse+ (default true) - if given display server already exists, should we use it or fail miserably?
   # * +dimensions+ (default 1280x1024x24) - display dimensions and depth. Not all combinations are possible, refer to +man Xvfb+.
+  # * +destroy_at_exit+ (default true) - if a display is started but not stopped, should it be destroyed when the script finishes?
   def initialize(options = {})
-    find_xvfb
+    CliUtil.ensure_application_exists!('Xvfb', 'Xvfb not found on your system')
 
     @display = options.fetch(:display, 99).to_i
     @reuse_display = options.fetch(:reuse, true)
     @dimensions = options.fetch(:dimensions, '1280x1024x24')
+    @video_capture_options = options.fetch(:video, {})
+    @destroy_at_exit = options.fetch(:destroy_at_exit, true)
 
     #TODO more logic here, autopicking the display number
     if @reuse_display
-      launch_xvfb unless read_pid
-    elsif read_pid
-      raise Exception.new("Display :#{display} is already taken and reuse=false")
+      launch_xvfb unless xvfb_running?
+    elsif xvfb_running?
+      raise Headless::Exception.new("Display :#{display} is already taken and reuse=false")
     else
       launch_xvfb
     end
-
-    raise Exception.new("Xvfb did not launch - something's wrong") unless read_pid
   end
 
   # Switches to the headless server
   def start
     @old_display = ENV['DISPLAY']
     ENV['DISPLAY'] = ":#{display}"
+    hook_at_exit
   end
 
   # Switches back from the headless server
@@ -86,7 +91,7 @@ class Headless
   # Switches back from the headless server and terminates the headless session
   def destroy
     stop
-    Process.kill('TERM', xvfb_pid) if read_pid
+    CliUtil.kill_process(pid_filename)
   end
 
   # Block syntax:
@@ -101,27 +106,44 @@ class Headless
     yield headless
     headless.destroy
   end
-
   class <<self; alias_method :ly, :run; end
 
-private
-  attr_reader :xvfb_pid
+  def video
+    @video_recorder ||= VideoRecorder.new(display, dimensions, @video_capture_options)
+  end
+
+  def take_screenshot(file_path)
+    CliUtil.ensure_application_exists!('import', "imagemagick not found on your system. Please install it using sudo apt-get install imagemagick")
 
-  def find_xvfb
-    @xvfb = `which Xvfb`.strip
-    raise Exception.new('Xvfb not found on your system') if @xvfb == ''
+    system "#{CliUtil.path_to('import')} -display localhost:#{display} -window root #{file_path}"
   end
 
+private
+
   def launch_xvfb
     #TODO error reporting
-    system "#{@xvfb} :#{display} -screen 0 #{dimensions} -ac >/dev/null 2>&1 &"
-    sleep 1
+    result = system "#{CliUtil.path_to("Xvfb")} :#{display} -screen 0 #{dimensions} -ac >/dev/null 2>&1 &"
+    raise Headless::Exception.new("Xvfb did not launch - something's wrong") unless result
+  end
+
+  def xvfb_running?
+    !!read_xvfb_pid
   end
 
-  def read_pid
-    @xvfb_pid=(File.read("/tmp/.X#{display}-lock") rescue "").strip.to_i
-    @xvfb_pid=nil if @xvfb_pid==0
-    @xvfb_pid
-    #TODO maybe check that the process still exists
+  def pid_filename
+    "/tmp/.X#{display}-lock"
+  end
+
+  def read_xvfb_pid
+    CliUtil.read_pid(pid_filename)
+  end
+    
+  def hook_at_exit
+    unless @at_exit_hook_installed
+      @at_exit_hook_installed = true
+      at_exit do
+        destroy if @destroy_at_exit
+      end
+    end
   end
 end

data/lib/headless/cli_util.rb

@@ -0,0 +1,52 @@
+class Headless
+  class CliUtil
+    def self.application_exists?(app)
+      `which #{app}`.strip != ""
+    end
+    
+    def self.ensure_application_exists!(app, error_message)
+      if !self.application_exists?(app)
+        raise Headless::Exception.new(error_message)
+      end
+    end
+
+    def self.path_to(app)
+      `which #{app}`.strip
+    end
+
+    def self.read_pid(pid_filename)
+      pid = (File.read(pid_filename) rescue "").strip.to_i
+      pid == 0 ? nil : pid
+    end
+
+    def self.fork_process(command, pid_filename, log_filename='/dev/null')
+      pid = fork do
+        STDERR.reopen(log_filename)
+        exec command
+        exit! 127 # safeguard in case exec fails
+      end
+      Process.detach(pid)
+
+      File.open pid_filename, 'w' do |f|
+        f.puts pid
+      end
+    end
+
+    def self.kill_process(pid_filename, options={})
+      if pid = self.read_pid(pid_filename)
+        begin
+          Process.kill 'TERM', pid
+          Process.wait pid if options[:wait]
+        rescue Errno::ESRCH
+          # no such process; assume it's already killed
+        end
+      end
+      
+      begin
+        FileUtils.rm pid_filename
+      rescue Errno::ENOENT
+        # pid file already removed
+      end
+    end
+  end
+end

data/lib/headless/video/video_recorder.rb

@@ -0,0 +1,46 @@
+require 'tempfile'
+
+class Headless
+  class VideoRecorder
+    attr_accessor :pid_file_path, :tmp_file_path, :log_file_path
+
+    def initialize(display, dimensions, options = {})
+      CliUtil.ensure_application_exists!('ffmpeg', 'Ffmpeg not found on your system. Install it with sudo apt-get install ffmpeg')
+
+      @display = display
+      @dimensions = dimensions
+
+      @pid_file_path = options.fetch(:pid_file_path, "/tmp/.headless_ffmpeg_#{@display}.pid")
+      @tmp_file_path = options.fetch(:tmp_file_path, "/tmp/.headless_ffmpeg_#{@display}.mov")
+      @log_file_path = options.fetch(:log_file_path, "/dev/null")
+    end
+
+    def capture_running?
+      !!@capture_running
+    end
+
+    def start_capture
+      CliUtil.fork_process("#{CliUtil.path_to('ffmpeg')} -y -r 30 -g 600 -s #{@dimensions} -f x11grab -i :#{@display} -vcodec qtrle #{@tmp_file_path}", @pid_file_path, @log_file_path)
+      @capture_running = true
+      at_exit do
+        stop_and_discard if capture_running?
+      end
+    end
+
+    def stop_and_save(path)
+      @capture_running = false
+      CliUtil.kill_process(@pid_file_path, :wait => true)
+      FileUtils.mv(@tmp_file_path, path)
+    end
+
+    def stop_and_discard
+      @capture_running = false
+      CliUtil.kill_process(@pid_file_path, :wait => true)
+      begin
+        FileUtils.rm(@tmp_file_path)
+      rescue Errno::ENOENT
+        # that's ok if the file doesn't exist
+      end
+    end
+  end
+end

data/spec/headless_spec.rb

@@ -0,0 +1,125 @@
+require 'lib/headless'
+
+describe Headless do
+  before do
+    ENV['DISPLAY'] = ":31337"
+    stub_environment
+  end
+
+  context "instaniation" do
+    context "when Xvfb is not installed" do
+      before do
+        Headless::CliUtil.stub!(:application_exists?).and_return(false)
+      end
+
+      it "raises an error" do
+        lambda { Headless.new }.should raise_error(Headless::Exception)
+      end
+    end
+
+    context "when Xvfb not started yet" do
+      it "starts Xvfb" do
+        Headless.any_instance.should_receive(:system).with("/usr/bin/Xvfb :99 -screen 0 1280x1024x24 -ac >/dev/null 2>&1 &").and_return(true)
+
+        headless = Headless.new
+      end
+
+      it "allows setting screen dimensions" do
+        Headless.any_instance.should_receive(:system).with("/usr/bin/Xvfb :99 -screen 0 1024x768x16 -ac >/dev/null 2>&1 &").and_return(true)
+
+        headless = Headless.new(:dimensions => "1024x768x16")
+      end
+    end
+
+    context "when Xvfb is already running" do
+      before do
+        Headless::CliUtil.stub!(:read_pid).and_return(31337)
+      end
+
+      it "raises an error if reuse display is not allowed" do
+        lambda { Headless.new(:reuse => false) }.should raise_error(Headless::Exception)
+      end
+
+      it "doesn't raise an error if reuse display is allowed" do
+        lambda { Headless.new(:reuse => true) }.should_not raise_error(Headless::Exception)
+        lambda { Headless.new }.should_not raise_error(Headless::Exception)
+      end
+    end
+  end
+
+  context "lifecycle" do
+    let(:headless) { Headless.new }
+    describe "#start" do
+      it "switches to the headless server" do
+        ENV['DISPLAY'].should == ":31337"
+        headless.start
+        ENV['DISPLAY'].should == ":99"
+      end
+    end
+
+    describe "#stop" do
+      it "switches back from the headless server" do
+        ENV['DISPLAY'].should == ":31337"
+        headless.start
+        ENV['DISPLAY'].should == ":99"
+        headless.stop
+        ENV['DISPLAY'].should == ":31337"
+      end
+    end
+
+    describe "#destroy" do
+      before do
+        Headless::CliUtil.stub!(:read_pid).and_return(4444)
+      end
+
+      it "switches back from the headless server and terminates the headless session" do
+        Process.should_receive(:kill).with('TERM', 4444)
+
+        ENV['DISPLAY'].should == ":31337"
+        headless.start
+        ENV['DISPLAY'].should == ":99"
+        headless.destroy
+        ENV['DISPLAY'].should == ":31337"
+      end
+    end
+  end
+
+  context "#video" do
+    let(:headless) { Headless.new }
+
+    it "returns video recorder" do
+      headless.video.should be_a_kind_of(Headless::VideoRecorder)
+    end
+
+    it "returns the same instance" do
+      recorder = headless.video
+      headless.video.should be_eql(recorder)
+    end
+  end
+
+  context "#take_screenshot" do
+    let(:headless) { Headless.new }
+
+    it "raises an error if imagemagick is not installed" do
+      Headless::CliUtil.stub!(:application_exists?).and_return(false)
+
+      lambda { headless.take_screenshot }.should raise_error(Headless::Exception)
+    end
+
+    it "issues command to take screenshot" do
+      headless = Headless.new
+
+      Headless.any_instance.should_receive(:system)
+
+      headless.take_screenshot("/tmp/image.png")
+    end
+  end
+
+private
+
+  def stub_environment
+    Headless::CliUtil.stub!(:application_exists?).and_return(true)
+    Headless::CliUtil.stub!(:read_pid).and_return(nil)
+    Headless::CliUtil.stub!(:path_to).and_return("/usr/bin/Xvfb")
+  end
+end

data/spec/video_recorder_spec.rb

@@ -0,0 +1,60 @@
+require 'lib/headless'
+
+describe Headless::VideoRecorder do
+  before do
+    stub_environment
+  end
+
+  describe "instaniation" do
+    before do
+      Headless::CliUtil.stub!(:application_exists?).and_return(false)
+    end
+
+    it "throws an error if ffmpeg is not installed" do
+        lambda { Headless::VideoRecorder.new(99, "1024x768x32") }.should raise_error(Headless::Exception)
+    end
+  end
+
+  describe "#capture" do
+    it "starts ffmpeg" do
+      Headless::CliUtil.stub(:path_to, 'ffmpeg').and_return('ffmpeg')
+      Headless::CliUtil.should_receive(:fork_process).with(/ffmpeg -y -r 30 -g 600 -s 1024x768x32 -f x11grab -i :99 -vcodec qtrle/, "/tmp/.headless_ffmpeg_99.pid", '/dev/null')
+
+      recorder = Headless::VideoRecorder.new(99, "1024x768x32")
+      recorder.start_capture
+    end
+  end
+
+  context "stopping video recording" do
+    subject do
+      recorder = Headless::VideoRecorder.new(99, "1024x768x32", :pid_file_path => "/tmp/pid", :tmp_file_path => "/tmp/ci.mov")
+      recorder.start_capture
+      recorder
+    end
+
+    describe "using #stop_and_save" do
+      it "stops video recording and saves file" do
+        Headless::CliUtil.should_receive(:kill_process).with("/tmp/pid", :wait => true)
+        FileUtils.should_receive(:mv).with("/tmp/ci.mov", "/tmp/test.mov")
+
+        subject.stop_and_save("/tmp/test.mov")
+      end
+    end
+
+    describe "using #stop_and_discard" do
+      it "stops video recording and deletes temporary file" do
+        Headless::CliUtil.should_receive(:kill_process).with("/tmp/pid", :wait => true)
+        FileUtils.should_receive(:rm).with("/tmp/ci.mov")
+
+        subject.stop_and_discard
+      end
+    end
+  end
+
+private
+
+  def stub_environment
+    Headless::CliUtil.stub!(:application_exists?).and_return(true)
+    Headless::CliUtil.stub!(:fork_process).and_return(true)
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: headless
 version: !ruby/object:Gem::Version 
-  hash: 27
-  prerelease: false
+  hash: 21
+  prerelease: 
   segments: 
   - 0
+  - 2
   - 1
-  - 0
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Leonid Shevtsov
@@ -15,10 +15,24 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-16 00:00:00 +03:00
+date: 2011-08-26 00:00:00 +03:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 2
+        - 6
+        version: "2.6"
+  type: :development
+  version_requirements: *id001
 description: "    Headless is a Ruby interface for Xvfb. It allows you to create a headless display straight from Ruby code, hiding some low-level action.\n"
 email: leonid@shevtsov.me
 executables: []
@@ -28,12 +42,20 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/headless.rb
+- .gitignore
 - CHANGELOG
-- README.md
+- Gemfile
 - LICENSE
+- README.md
+- Rakefile
+- headless.gemspec
+- lib/headless.rb
+- lib/headless/cli_util.rb
+- lib/headless/video/video_recorder.rb
+- spec/headless_spec.rb
+- spec/video_recorder_spec.rb
 has_rdoc: true
-homepage: http://github.com/leonid-shevtsov/headless
+homepage: http://leonid.shevtsov.me/en/headless
 licenses: []
 
 post_install_message: 
@@ -62,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: 
 - Xvfb
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Ruby headless display interface