te3270 0.1-x86-mingw32

data/lib/te3270/screen_factory.rb

@@ -0,0 +1,49 @@
+require 'page_navigation'
+
+module TE3270
+  #
+  # Module to facilitate to creating of screen objects in step definitions.  You
+  # can make the methods below available to all of your step definitions by adding
+  # this module to World.
+  #
+  # @example Making the ScreenFactory available to your step definitions
+  #   World TE3270::ScreenFactory
+  #
+  # @example using a screen in a Scenario
+  #   on MyScreen do |screen|
+  #     screen.name = 'Cheezy'
+  #   end
+  #
+  # If you plan to use the +navigate_to+ method you will need to ensure
+  # you setup the possible routes ahead of time.  You must always have
+  # a default route in order for this to work.  Here is an example of
+  # how you define routes:
+  #
+  # @example Example routes defined in env.rb
+  #   TE3270::ScreenFactory.routes = {
+  #     :default => [[ScreenOne,:method1], [ScreenTwo,:method2], [ScreenThree,:method3]],
+  #     :another_route => [[ScreenOne,:method1, "arg1"], [ScreenTwo,:method2b], [ScreenThree,:method3]]
+  #   }
+  #
+  # Notice the first entry of :another_route is passing an argument
+  # to the method.
+  #
+  module ScreenFactory
+    include PageNavigation
+
+    #
+    # Create a screen object.  Also sets an instance variable +@current_screen
+    #
+    # @param [Class]  screen_class a class that has included the TE3270 module
+    # @param [block]  an optional block to be called
+    # @return [ScreenObject] the newly created screen object
+    #
+    def on(screen_class, &block)
+      raise '@emulator instance variable must be available to use the ScreenFactory methods' unless @emulator
+      @current_screen = screen_class.new @emulator
+      block.call @current_screen if block
+      @current_screen
+    end
+
+  end
+end

data/lib/te3270/version.rb

@@ -0,0 +1,4 @@
+module TE3270
+  VERSION = "0.1"
+end
+

data/lib/te3270.rb

@@ -0,0 +1,166 @@
+require 'te3270/version'
+require 'te3270/accessors'
+require 'te3270/screen_factory'
+require 'te3270/function_keys'
+require 'te3270/emulator_factory'
+require 'te3270/emulators/extra'
+require 'te3270/emulators/quick3270'
+
+#
+# This gem can be used to drive a 3270 terminal emulator.  You have to have a supported emulator installed on the
+# machines on which you use the gem.  Currently the only supported emulators are EXTRA! X-treme by Attachmate and
+# Quick3270 by DN-Computing.  These are commercial products and you will need to purchase one of them in order to
+# use this gem.  We do plan to support other emulators as time permits.
+#
+# This gem has been designed to work very similar to the page-object gem.  You will use it to create screen objects
+# for each screen in your application.  Here is an example of one and how it can be used:
+#
+# @example Example mainframe page
+#   class MainframeScreen
+#     include TE3270
+#
+#     text_field(:userid, 10, 30, 20, true)
+#     text_field(:password, 12, 30, 20, true)
+#   end
+#
+#    ...
+#
+#   emulator = TN3270.emulator_for :extra do |emulator|
+#     emulator.session_file = 'path_to_session_file'
+#   end
+#   my_screen = MainframeScreen.new(emulator)
+#   my_screen.userid = 'the_id'
+#   my_screen.password = 'the_password'
+#
+# Another option is to mixin the +TE3270::ScreenFactory+ module on use the factory methods to create the screen
+# objects.  If you are using Cucumber you can do this by calling the +World+ method in your env.rb file.  Then
+# you can use the factory and navigation methods in your step definitions.
+#
+# @example Registering the ScreenFactory with Cucumber World
+#   World(TE3270::ScreenFactory)
+#
+#   Before do
+#     @emulator = TE3270.emulator_for :quick3270 do |emulator|
+#       emulator.session_file = 'path_to_session_file'
+#     end
+#   end
+#
+#
+# @example Using the factory method in a step definition
+#   on(MainframeScreen).do_something
+#
+#
+# @see  #TE3270::ScreenFactory for more details on using the factory and navigation methods
+#
+module TE3270
+  extend FunctionKeys
+
+  def self.included(cls)
+    cls.extend TE3270::Accessors
+  end
+
+  #
+  # Starts the terminal emulator and makes the connection.  This method requires a block
+  # that has emulator specific information that is necessary to complete the connection.
+  # To know what information you should provide in the block please see the classes in
+  # the TE3270::Emulators package.
+  #
+  #@param platform =[:extra,:quick3270] use :extra for Extra emulator and :quick3270 for quick emulator
+  #
+  def self.emulator_for(platform, &block)
+    platform_class = TE3270::EmulatorFactory.emulator_for(platform)
+    @platform = platform_class.new
+    @platform.connect &block
+    @platform
+  end
+
+  #
+  # Disconnects and closes the emulator
+  #
+  def self.disconnect(emulator)
+    emulator.disconnect
+  end
+
+  def initialize(platform)
+    @platform = platform
+    initialize_screen if respond_to? :initialize_screen
+  end
+
+  #
+  # Open a new screen and connect to the host.  Platform specific values are set by
+  # passing a block to this method.  To see the valid platform specific values please
+  # read the documentation for your emulator class in the TE3270::Emulators module.
+  #
+  def connect
+    platform.connect
+  end
+
+  #
+  # Disconnect from platform (extra or quick)
+  #
+  def disconnect
+    platform.disconnect
+  end
+
+  #
+  # Send keys on the emulator
+  #
+  def send_keys(keys)
+    platform.send_keys(keys)
+  end
+
+  #
+  # Retrieves the text from the current screen
+  #
+  def text
+    platform.text
+  end
+
+  #
+  # Takes screenshot and saves to the filename specified.  If you have visibility set to false
+  # then this method will first of all make the screen visible, take the screenshot, and then
+  # make set visibility to false again.
+  #
+  # @param [String] filename of the file to be saved.
+  #
+  def screenshot(filename)
+    platform.screenshot(filename)
+  end
+
+  #
+  # Waits for the string to appear at the specified location
+  #
+  # @param [String] String to wait for
+  # @param [FixedNum] row number
+  # @param [FixedNum] column number
+  #
+  def wait_for_string(str, row, column)
+    platform.wait_for_string(str, row, column)
+  end
+
+  #
+  # Waits for the host for specified # of seconds. Default is 5 seconds
+  #
+  # @param [FixedNum] seconds to wait for
+  #
+  def wait_for_host(seconds=5)
+    platform.wait_for_host(seconds)
+  end
+
+  #
+  # Waits for the cursor to appear at the specified location
+  #
+  # @param [FixedNum] row number
+  # @param [FixedNum] column number
+  #
+  def wait_until_cursor_at(row, column)
+    platform.wait_until_cursor_at(row, column)
+  end
+
+  private
+
+  def platform
+    @platform ||= Extra.new
+  end
+
+end

data/spec/lib/te3270/accessors_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+class AccessorsTestScreen
+  include TE3270
+
+  text_field(:method_name, 1, 2, 10, true)
+  text_field(:read_only, 2, 3, 12, false)
+  text_field(:default_editable, 3, 4, 14)
+end
+
+describe TE3270::Accessors do
+
+  let(:platform) { double('platform') }
+  let(:screen_object) { AccessorsTestScreen.new platform }
+
+  before(:each) do
+    screen_object.stub(:platform).and_return platform
+  end
+
+  describe "text_field accessors" do
+
+    it 'should generate a method to retrieve the value' do
+      screen_object.should respond_to :method_name
+    end
+
+    it 'should generate a method to set the value' do
+      screen_object.should respond_to :method_name=
+    end
+
+    it 'should not generate a method to set the value if it is not editable' do
+      screen_object.should_not respond_to :read_only=
+    end
+
+    it 'should default to being editable when it is not specified' do
+      screen_object.should respond_to :default_editable=
+    end
+
+    it 'should use the platform to get the text value' do
+      platform.should_receive(:get_string).with(1, 2, 10).and_return('abc')
+      screen_object.method_name.should == 'abc'
+    end
+
+    it 'should use the platform to set the text value' do
+      platform.should_receive(:put_string).with('abc', 1, 2)
+      screen_object.method_name = 'abc'
+    end
+
+  end
+
+end

data/spec/lib/te3270/emulators/extra_spec.rb

@@ -0,0 +1,182 @@
+require 'spec_helper'
+
+describe TE3270::Emulators::Extra do
+
+  let(:extra) { TE3270::Emulators::Extra.new }
+
+  before(:each) do
+    WIN32OLE.stub(:new).and_return extra_system
+    extra.instance_variable_set(:@session_file, 'the_file')
+    File.stub(:exists).and_return false
+  end
+
+
+  describe "global behaviors" do
+    it 'should start a new terminal' do
+      WIN32OLE.should_receive(:new).and_return(extra_system)
+      extra.connect
+    end
+
+    it 'should open a session' do
+      extra_sessions.should_receive(:Open).and_return(extra_session)
+      extra.connect
+    end
+
+    it 'should not display the splash screen if version is higher than 9' do
+      extra_system.should_receive(:Version).and_return("9.2")
+      extra_sessions.should_receive(:VisibleOnStartup=).with(true)
+      extra.connect
+    end
+
+    it 'should call a block allowing the session file to be set' do
+      extra_sessions.should_receive(:Open).with('blah.edp').and_return(extra_session)
+      extra.connect do |platform|
+        platform.session_file = 'blah.edp'
+      end
+    end
+
+    it 'should raise an error when the session file is not set' do
+      extra.instance_variable_set(:@session_file, nil)
+      expect { extra.connect }.to raise_error('The session file must be set in a block when calling connect with the Extra emulator.')
+    end
+
+    it 'should take the visible value from a block' do
+      extra_session.should_receive(:Visible=).with(false)
+      extra.connect do |platform|
+        platform.visible = false
+      end
+    end
+
+    it 'should default to visible when not specified' do
+      extra_session.should_receive(:Visible=).with(true)
+      extra.connect
+    end
+
+    it 'should take the window state value from the block' do
+      extra_session.should_receive(:WindowState=).with(2)
+      extra.connect do |platform|
+        platform.window_state = :maximized
+      end
+    end
+
+    it 'should default to window state normal when not specified' do
+      extra_session.should_receive(:WindowState=).with(1)
+      extra.connect
+    end
+
+    it 'should default to being visible' do
+      extra_session.should_receive(:Visible=).with(true)
+      extra.connect
+    end
+
+    it 'should get the screen for the active session' do
+      extra_session.should_receive(:Screen).and_return(extra_screen)
+      extra.connect
+    end
+
+    it 'should get the area from the screen' do
+      extra_screen.should_receive(:SelectAll).and_return(extra_area)
+      extra.connect
+    end
+
+    it 'should disconnect from a session' do
+      extra_system.should_receive(:Quit)
+      extra.connect
+      extra.disconnect
+    end
+  end
+
+  describe "interacting with text fields" do
+    it 'should get the value from the screen' do
+      extra_screen.should_receive(:GetString).with(1, 2, 10).and_return('blah')
+      extra.connect
+      extra.get_string(1, 2, 10).should == 'blah'
+    end
+
+    it 'should put the value on the screen' do
+      wait_collection = double('wait')
+      extra_screen.should_receive(:PutString).with('blah', 1, 2)
+      extra_screen.should_receive(:WaitHostQuiet).and_return(wait_collection)
+      wait_collection.should_receive(:Wait).with(1000)
+      extra.connect
+      extra.put_string('blah', 1, 2)
+    end
+  end
+
+  describe "interacting with the screen" do
+    it 'should know how to send function keys' do
+      wait_collection = double('wait')
+      extra_screen.should_receive(:SendKeys).with('<Clear>')
+      extra_screen.should_receive(:WaitHostQuiet).and_return(wait_collection)
+      wait_collection.should_receive(:Wait).with(1000)
+      extra.connect
+      extra.send_keys(TE3270.Clear)
+    end
+
+    it 'should wait for a string to appear' do
+      wait_col = double('wait')
+      extra_screen.should_receive(:WaitForString).with('The String', 3, 10).and_return(wait_col)
+      extra_system.should_receive(:TimeoutValue).and_return(30000)
+      wait_col.should_receive(:Wait).with(30000)
+      extra.connect
+      extra.wait_for_string('The String', 3, 10)
+    end
+
+    it 'should wait for the host to be quiet' do
+      wait_col = double('wait')
+      extra_screen.should_receive(:WaitHostQuiet).and_return(wait_col)
+      wait_col.should_receive(:Wait).with(4000)
+      extra.connect
+      extra.wait_for_host(4)
+    end
+
+    it 'should wait until the cursor is at a position' do
+      wait_col = double('wait')
+      extra_screen.should_receive(:WaitForCursor).with(5, 8).and_return(wait_col)
+      extra_system.should_receive(:TimeoutValue).and_return(30000)
+      wait_col.should_receive(:Wait).with(30000)
+      extra.connect
+      extra.wait_until_cursor_at(5, 8)
+    end
+
+    it 'should take screenshots' do
+      take = double('Take')
+      extra_session.should_receive(:WindowHandle).and_return(123)
+      Win32::Screenshot::Take.should_receive(:of).with(:window, hwnd: 123).and_return(take)
+      take.should_receive(:write).with('image.png')
+      extra.connect
+      extra.screenshot('image.png')
+    end
+
+    it 'should make the window visible before taking a screenshot' do
+      take = double('Take')
+      extra_session.should_receive(:WindowHandle).and_return(123)
+      Win32::Screenshot::Take.should_receive(:of).with(:window, hwnd: 123).and_return(take)
+      take.should_receive(:write).with('image.png')
+      extra_session.should_receive(:Visible=).once.with(true)
+      extra_session.should_receive(:Visible=).twice.with(false)
+      extra.connect do |emulator|
+        emulator.visible = false
+      end
+      extra.screenshot('image.png')
+    end
+
+    it 'should delete the file for the screenshot if it already exists' do
+      File.should_receive(:exists?).and_return(true)
+      File.should_receive(:delete)
+      take = double('Take')
+      extra_session.should_receive(:WindowHandle).and_return(123)
+      Win32::Screenshot::Take.should_receive(:of).with(:window, hwnd: 123).and_return(take)
+      take.should_receive(:write).with('image.png')
+      extra.connect
+      extra.screenshot('image.png')
+    end
+
+    it "should get the screen text" do
+      extra_area.should_receive(:Value).and_return('blah')
+      extra.connect
+      extra.text.should == 'blah'
+    end
+
+  end
+end

data/spec/lib/te3270/emulators/quick3270_spec.rb

@@ -0,0 +1,166 @@
+require 'spec_helper'
+
+describe TE3270::Emulators::Quick3270 do
+
+  let(:quick) { TE3270::Emulators::Quick3270.new }
+
+  before(:each) do
+    WIN32OLE.stub(:new).and_return quick_system
+    quick.instance_variable_set(:@session_file, 'the_host')
+  end
+
+  describe "global behaviors" do
+    it 'should start new terminal' do
+      WIN32OLE.should_receive(:new).and_return(quick_system)
+      quick.connect
+    end
+
+    it 'should establish a session' do
+      quick_system.should_receive(:ActiveSession).and_return(quick_session)
+      quick.connect
+    end
+
+    it 'should get the screen from the active session' do
+      quick_session.should_receive(:Screen).and_return(quick_screen)
+      quick.connect
+    end
+
+    it 'should take the Visible value from a block' do
+      quick_system.should_receive(:Visible=).with(false)
+      quick.connect do |platform|
+        platform.visible = false
+      end
+    end
+
+    it 'should take the session file from a block' do
+      quick.should_receive(:session_file=).with('blah.txt')
+      quick.connect do |platform|
+        platform.session_file = 'blah.txt'
+      end
+    end
+
+    it 'should display an error when the session file is not set' do
+      quick.instance_variable_set(:@session_file, nil)
+      expect { quick.connect }.to raise_error('The session file must be set in a block when calling connect with the Quick3270 emulator.')
+    end
+
+    it 'should open the connection using the sesion file' do
+      quick_session.should_receive(:Open).with('blah.txt')
+      quick.connect do |platform|
+        platform.session_file = 'blah.txt'
+      end
+    end
+
+    it 'should default to Visible being true when not provided' do
+      quick_system.should_receive(:Visible=).with(true)
+      quick.connect
+    end
+
+    it 'should make the connection via the session' do
+      quick_session.should_receive(:Connect)
+      quick.connect
+    end
+
+    it 'should check to make sure the connection is successful before continuing' do
+      quick_session.should_receive(:Connected).once.and_return(false)
+      quick_screen.should_receive(:WaitHostQuiet).once.with(1000)
+      quick_session.should_receive(:Connected).once.and_return(true)
+      quick.connect
+    end
+
+    it 'should disconnect from a session' do
+      application = double('application')
+      quick_session.should_receive(:Disconnect)
+      quick_system.should_receive(:Application).and_return(application)
+      application.should_receive(:Quit)
+      quick.connect
+      quick.disconnect
+    end
+  end
+
+  describe "interacting with text fields" do
+    it 'should get the value from the screen' do
+      quick_screen.should_receive(:GetString).with(1, 2, 7).and_return('blah')
+      quick.connect
+      quick.get_string(1, 2, 7).should == 'blah'
+    end
+
+    it 'should put a value on the screen' do
+      quick_screen.should_receive(:MoveTo).with(15, 56)
+      quick_screen.should_receive(:PutString).with('blah')
+      quick_screen.should_receive(:WaitHostQuiet).with(3000)
+      quick.connect
+      quick.put_string('blah', 15, 56)
+    end
+  end
+
+  describe "interacting with the screen" do
+    it 'should know how to send function keys' do
+      quick_screen.should_receive(:SendKeys).with('<Home>')
+      quick_screen.should_receive(:WaitHostQuiet).with(3000)
+      quick.connect
+      quick.send_keys(TE3270.Home)
+    end
+
+    it 'should wait for a string to appear' do
+      quick_screen.should_receive(:WaitForString).with('string', 3, 10)
+      quick.connect
+      quick.wait_for_string('string', 3, 10)
+    end
+
+    it 'should wait for the host to be quiet' do
+      quick_screen.should_receive(:WaitHostQuiet).with(6000)
+      quick.connect
+      quick.wait_for_host(6)
+    end
+
+    it 'should wait until the cursor is at a position' do
+      quick_screen.should_receive(:WaitForCursor).with(5, 8)
+      quick.connect
+      quick.wait_until_cursor_at(5,8)
+    end
+
+    it 'should take screenshots' do
+      take = double('Take')
+      quick_system.should_receive(:WindowTitle).and_return('The Title')
+      Win32::Screenshot::Take.should_receive(:of).with(:window, title: 'The Title').and_return(take)
+      take.should_receive(:write).with('image.png')
+      quick.connect
+      quick.screenshot('image.png')
+    end
+
+    it 'should delete the file for the screenshot if it already exists' do
+      File.should_receive(:exists?).and_return(true)
+      File.should_receive(:delete)
+      take = double('Take')
+      quick_system.should_receive(:WindowTitle).and_return('The Title')
+      Win32::Screenshot::Take.should_receive(:of).with(:window, title: 'The Title').and_return(take)
+      take.should_receive(:write).with('image.png')
+      quick.connect
+      quick.screenshot('image.png')
+    end
+
+    it 'should make the window visible before taking a screenshot' do
+      take = double('Take')
+      quick_system.should_receive(:WindowTitle).and_return('The Title')
+      Win32::Screenshot::Take.should_receive(:of).with(:window, title: 'The Title').and_return(take)
+      take.should_receive(:write).with('image.png')
+      quick_system.should_receive(:Visible=).once.with(true)
+      quick_system.should_receive(:Visible=).twice.with(false)
+      quick.connect do |emulator|
+        emulator.visible = false
+      end
+      quick.screenshot('image.png')
+    end
+
+    it 'should get the screen text' do
+      quick_screen.should_receive(:Rows).and_return(3)
+      quick_screen.should_receive(:Cols).and_return(10)
+      3.times do |time|
+        quick_screen.should_receive(:GetString).with(time+1, 1, 10).and_return("row #{time}")
+      end
+      quick.connect
+      quick.text.should == 'row 0\nrow 1\nrow 2\n'
+    end
+  end
+end

data/spec/lib/te3270/screen_factory_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+class ScreenFactoryScreen
+  include TE3270
+end
+
+class World
+  include TE3270::ScreenFactory
+end
+
+describe TE3270::ScreenFactory do
+
+  let(:world) { World.new }
+
+  it 'should create a new screen object' do
+    emulator = double('platform')
+    world.instance_variable_set('@emulator', emulator)
+    world.on(ScreenFactoryScreen).should be_instance_of ScreenFactoryScreen
+  end
+
+  it 'should create a new screen object and execute a block' do
+    emulator = double('platform')
+    world.instance_variable_set('@emulator', emulator)
+    world.on(ScreenFactoryScreen) do |page|
+      page.should be_instance_of ScreenFactoryScreen
+    end
+  end
+
+  it 'should raise an error when an @emulator instance variable does not exist' do
+    expect { world.on(ScreenFactoryScreen) }.to raise_error("@emulator instance variable must be available to use the ScreenFactory methods")
+  end
+end