Class Sprout::FDBTask
In: bundles/as3/lib/sprout/tasks/fdb_task.rb
Parent: ToolTask

The FDBTask provides a procedural rake front end to the FDB command line tool

Here is a decent tutorial on using FDB with SWF or HTML content: installingcats.wordpress.com/tag/adobe-flex/

You can send the fdb task some debug commands directly or simply execute the rake task and interact with the debugger manually.

The FDBTask requires that you have a debug Flash Player installed on your system as the default execution application for SWF files.

Following is an example of setting up a breakpoint in SomeFile at line 23

  fdb :debug do |t|
    t.file = 'bin/SomeProject-debug.swf'
    t.run
    t.break = 'SomeFile:23'
    t.continue
  end

You can also point the FDBTask at HTML pages. These pages will be launched in your default browser. You will need to manually install a debug Flash Player in that particular browser.

To use a browser instead of the desktop Flash Player, simply point the file argument at an HTML document or remote URL. The SWF file loaded must be compiled using the -debug flag, and executed in a debug Flash Player in order to connect to properly connect to the debugger.

  fdb :debug do |t|
    t.file = 'bin/SomeProject-debug.html'
    t.run
    t.continue
  end

.h3 Continuous Integration

The FDBTask is also the only effective way to execute SWF content in front of a CI (continuous integration) tool like Cruise Control. The biggest problem facing SWF execution for CI is uncaught runtime exceptions. The debug Flash Player throws uncaught exceptions up to the operating system GUI layer where a user must manually dismiss a dialog. In addition to blocking the CI process indefinitely, these messages are also difficult to capture and log.

Using Sprouts and the FDBTask, we can capture these messages along with additonal information (e.g. local variables and a complete stack trace) about the state of the SWF file, and then cleanly exit the Flash Player and log this information.

The FDBTask has also been configured to work with the ASUnit XMLPrinter so that an XML artifact is created and written to disk that includes the results of running your test suites.

To use FDB with a CI tool do the following:

1) Create a new base runner class (we usually name this XMLRunner.as) and make it look like the following:

  package {
    import asunit.textui.TestRunner;
    import asunit.textui.XMLResultPrinter;

    public class XMLRunner extends TestRunner {

      public function XMLRunner() {
        setPrinter(new XMLResultPrinter());
        start(AllTests, null, TestRunner.SHOW_TRACE);
      }
    }
  }

2) Create a new MXMLCTask to compile the newly created runner. NOTE: Be sure you set debug to true, otherwise the SWF will not connect to the debugger properly.

  library :asunit3

  desc 'Compile the CI SWF'
  mxmlc 'bin/XMLRunner.swf' => :asunit3 do |t|
    t.input = 'src/XMLRunner.as'
    t.debug = true
    t.source_path << 'test'
    # Add additional configuration here.
  end

3) Create a new FDBTask and set kill_on_fault to true.

  desc 'Execute the test harness for CI'
  fdb :cruise do |t|
    t.kill_on_fault = true
    t.file = 'bin/XMLRunner.swf'
    t.run
    t.continue
  end

4) Configure your CI task to call:

  rake cruise

5) That‘s it!

Methods

Constants

TEST_RESULT_PRELUDE = '<XMLResultPrinter>'
TEST_RESULT_CLOSING = '</XMLResultPrinter>'
TEST_RESULT_FILE = 'AsUnitResults.xml'

Attributes

kill_on_fault  [W]  Boolean value that tells fdb whether or not it should automatically shut down when an exception is encountered. This feature is used to prevent GUI prompts for unhandled exceptions, especially when running a test harness under a continuous integration tool - like cruise control. If an exception is encountered, fdb will automatically print the exception, a full stack trace and all local variables in the function where the failure occured.
test_result_closing  [W]  String that indicates the closing of printable test results Default value is ’</XMLResultPrinter>’ See test_result_prelude for more info.
test_result_file  [W]  Relative or absolute path to where unit test results should be written to disk. This field can be used in conjunction with the AsUnit XMLResultPrinter which will trace out JUnit style XML test results. By telling fdb where to write those test results, it will scan the trace output stream looking for test_result_prelude, and test_result_closing. Once the closing is encountered, the prelude and closing (and everything in between) will be written to disk in the file identified by test_result_file, and fdb will be closed down.
test_result_prelude  [W]  String that indicates the beginning of printable test results Default value is ’<XMLResultPrinter>’

Public Instance methods

Set breakpoint at specified line or function

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 246
    def break=(point)
      @queue << "break #{point}"
    end

Print backtrace of all stack frames

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 241
    def bt
      @queue << "bt"
    end

Alias for continue

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 271
    def c
      @queue << "continue"
    end

Display the name and number of the current file

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 251
    def cf
      @queue << "cf"
    end

Clear breakpoint at specified line or function

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 256
    def clear=(point)
      @queue << "clear #{point}"
    end

Sets commands to execute when breakpoint hit

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 276
    def commands=(cmd)
      @queue << "com #{cmd}"
    end

Apply/remove conditional expression to a breakpoint

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 261
    def condition=(cond)
      @queue << "condition #{cond}"
    end

Continue execution after stopping at breakpoint

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 266
    def continue
      @queue << "continue"
    end

Delete breakpoints or auto-display expressions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 281
    def delete
      @queue << "delete"
    end

Add a directory to the search path for source files

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 286
    def directory=(dir)
      @queue << "directory #{dir}"
    end

Disable breakpoints or auto-display expressions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 291
    def disable
      @queue << "disable"
    end

Disassemble source lines or functions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 296
    def disassemble
      @queue << "dissassemble"
    end

Add an auto-display expressions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 301
    def display=(disp)
      @queue << "disp #{disp}"
    end

Enable breakpoints or auto-display expressions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 311
    def e
      @queue << "enable"
    end

Enable breakpoints or auto-display expressions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 306
    def enable
      @queue << "enable"
    end

Specify application to be debugged.

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 316
    def file=(file)
      @prerequisites << file
      @queue << "file #{file}"
      @file = file
    end

Execute until current function returns

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 328
    def finish
      @queue << "finish"
    end

Specify how to handle a fault

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 333
    def handle
      @queue << "handle"
    end

Set listing location to where execution is halted

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 338
    def home
      @queue << "home"
    end

Display information about the program being debugged

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 343
    def info
      @queue << "info"
    end

Argument variables of current stack frame

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 348
    def info_arguments
      @queue << "i a"
    end

Status of user-settable breakpoints

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 353
    def info_breakpoints
      @queue << "i b"
    end

Display list of auto-display expressions

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 358
    def info_display
      @queue << "i d"
    end

Names of targets and files being debugged

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 363
    def info_files
      @queue << "i f"
    end

All function names

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 368
    def info_functions=(value)
      @queue << "i fu #{value}"
    end

How to handle a fault

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 373
    def info_handle
      @queue << "i h"
    end

Local variables of current stack frame

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 378
    def info_locals
      @queue << "i l"
    end

Scope chain of current stack frame

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 383
    def info_scopechain
      @queue << "i sc"
    end

Source files in the program

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 388
    def info_sources
      @queue << "i so"
    end

Backtrace of the stack

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 393
    def info_stack
      @queue << "i s"
    end

List of swfs in this session

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 398
    def info_swfs
      @queue << "i sw"
    end

Application being debugged

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 403
    def info_targets
      @queue << "i t"
    end

All global and static variable names

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 408
    def info_variables
      @queue << "i v"
    end

alias for self.file=

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 323
    def input=(file)
      self.file = file
    end

Kill execution of program being debugged

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 413
    def kill
      @queue << "kill"
    end

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 224
    def kill_on_fault?
      @kill_on_fault
    end

List specified function or line

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 418
    def list
      @queue << "list"
    end

Step program

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 423
    def next
      @queue << "next"
    end

Print value of variable EXP

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 428
    def print=(msg)
      @queue << "print #{msg}"
    end

Print working directory

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 433
    def pwd
      @queue << "pwd"
    end

Exit fdb

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 438
    def quit
      @queue << "quit"
      @queue << "y"
      @queue << "terminate"
    end

Start debugged program

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 445
    def run
      @queue << "run"
    end

Set the value of a variable

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 450
    def set=(value)
      @queue << "set #{value}"
    end

Sleep until some ‘str’ String is sent to the output,

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 455
    def sleep_until(str)
      @queue << "sleep #{str}"
    end

Read fdb commands from a file

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 460
    def source=(file)
      @queue << "source #{file}"
    end

Step program until it reaches a different source line

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 465
    def step
      @queue << "step"
    end

Force the Flash Debugger and running SWF to close

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 470
    def terminate
      @queue << "terminate"
    end

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 236
    def test_result_closing
      @test_result_closing ||= TEST_RESULT_CLOSING
    end

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 228
    def test_result_file
      @test_result_file ||= TEST_RESULT_FILE
    end

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 232
    def test_result_prelude
      @test_result_prelude ||= TEST_RESULT_PRELUDE
    end

Remove an auto-display expression

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 475
    def undisplay
      @queue << "undisplay"
    end

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 166
    def validate_swf(swf)
      # TODO: Ensure the SWF has been compiled with debugging
      # turned on.
      # I believe this will require actually parsing the SWF file and
      # scanning for the EnableDebugger2 tag.
      # http://www.adobe.com/devnet/swf/pdf/swf_file_format_spec_v9.pdf
    end

Set or clear filter for file listing based on swf

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 480
    def viewswf
      @queue << "viewswf"
    end

Displays the context of a variable

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 485
    def what=(value)
      @queue << "what #{value}"
    end

Same as bt

[Source]

# File bundles/as3/lib/sprout/tasks/fdb_task.rb, line 490
    def where
      @queue << "bt"
    end

[Validate]