Changeset 742

Timestamp:

07/23/07 16:45:04 (1 year ago)

Author:

kindlund

Message:

Documentation and unit testing complete for FF browser.

Files:

• honeyclient/branches/exp/kindlund-firefox/lib/HoneyClient/Agent/Driver/Browser/FF.pm (modified) (10 diffs)
• honeyclient/branches/exp/kindlund-firefox/t/honeyclient_agent_driver_browser_ff.t (modified) (1 diff)

honeyclient/branches/exp/kindlund-firefox/lib/HoneyClient/Agent/Driver/Browser/FF.pm

@@ -1 @@
-########
+
-# Created on:  May 11, 2006
-# Package:     HoneyClient::Agent::Driver::FF
@@ -9 +9 @@
-# CVS: $Id$
-#
-xkovah, kindlund, ttruong
+ttruong, kindlund, stephenson
-#
-# Copyright (C) 2007 The MITRE Corporation.  All rights reserved.
@@ -28 +28 @@
-# 02110-1301, USA.
-#
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-package HoneyClient::Agent::Driver::Browser::FF;
-
-# XXX: Disabled version check, Honeywall does not have Perl v5.8 installed.
-#use 5.008006;
-use strict;
-use warnings;
-use Config;
-use Carp ();
-
@@ -71 +178 @@
-    # Do not simply export all your public functions/methods/constants.
-
-IE
+FF
-    # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
-    # will save memory.
@@ -84 +191 @@
-    @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
-
-# XXX: Fix this!
-# Check to make sure our OS is Windows-based.
-#if ($Config{osname} !~ /^MSWin32$/) {
-#    Carp::croak "Error: " . __PACKAGE__ . " will only run on Win32 platforms!\n";
-#}
-
-    $SIG{PIPE} = 'IGNORE';    # Do not exit on broken pipes.
-}
-our ( @EXPORT_OK, $VERSION );
-
-#TODO: Rewrite the test module
-
-=pod
-
-=begin testing
-
+# Make sure Log::Log4perl loads
+BEGIN { use_ok('Log::Log4perl', qw(:nowarn))
+        or diag("Can't load Log::Log4perl package. Check to make sure the package library is correctly listed within the path.");
+       
+        # Suppress all logging messages, since we need clean output for unit testing.
+        Log::Log4perl->init({
+            "log4perl.rootLogger"                               => "DEBUG, Buffer",
+            "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer",
+            "log4perl.appender.Buffer.min_level"                => "fatal",
+            "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout",
+            "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n",
+        });
+}
+require_ok('Log::Log4perl');
+use Log::Log4perl qw(:easy);
+
+# Make sure HoneyClient::Util::Config loads.
+BEGIN { use_ok('HoneyClient::Util::Config', qw(getVar))
+        or diag("Can't load HoneyClient::Util::Config package.  Check to make sure the package library is correctly listed within the path."); 
+
+        # Suppress all logging messages, since we need clean output for unit testing.
+        Log::Log4perl->init({
+            "log4perl.rootLogger"                               => "DEBUG, Buffer",
+            "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer",
+            "log4perl.appender.Buffer.min_level"                => "fatal",
+            "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout",
+            "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n",
+        });
+        
+}
+require_ok('HoneyClient::Util::Config');
+can_ok('HoneyClient::Util::Config', 'getVar');
+use HoneyClient::Util::Config qw(getVar);
+
+# Make sure the module loads properly, with the exportable
+# functions shared.
+BEGIN { use_ok('HoneyClient::Agent::Driver::Browser::FF') or diag("Can't load HoneyClient::Agent::Driver::Browser::FF package.  Check to make sure the package library is correctly listed within the path."); }
+require_ok('HoneyClient::Agent::Driver::Browser::FF');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'new');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'drive');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'isFinished');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'next');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'status');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'getNextLink');
+use HoneyClient::Agent::Driver::Browser::FF;
+
+# Suppress all logging messages, since we need clean output for unit testing.
+Log::Log4perl->init({
+    "log4perl.rootLogger"                               => "DEBUG, Buffer",
+    "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer",
+    "log4perl.appender.Buffer.min_level"                => "fatal",
+    "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout",
+    "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n",
+});
+
+# Make sure Win32::Job loads.
+BEGIN { use_ok('Win32::Job') or diag("Can't load Win32::Job package.  Check to make sure the package library is correctly listed within the path."); }
+require_ok('Win32::Job');
+use Win32::Job;
+
+# Make sure ExtUtils::MakeMaker loads.
+BEGIN { use_ok('ExtUtils::MakeMaker', qw(prompt)) or diag("Can't load ExtUtils::MakeMaker package.  Check to make sure the package library is correctly listed within the path."); }
+require_ok('ExtUtils::MakeMaker');
+can_ok('ExtUtils::MakeMaker', 'prompt');
+use ExtUtils::MakeMaker qw(prompt);
+
-=end testing
-
@@ -105 +270 @@
-
-#######################################################################
-
-#TODO: Remove any of these use statements that aren't needed
-
-# Include the Global Configuration Processing Library
-use HoneyClient::Util::Config qw(getVar);
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-use Win32::Job;
-
@@ -140 +283 @@
-our $LOG = get_logger();
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-sub drive {
@@ -212 +409 @@
-    }
-
-IE
+FF
-    $self = $self->SUPER::drive(%args);
-
+
-    # Sanity check: Make sure our next URL is defined.
-    unless (defined($args{'url'})) {
@@ -230 +427 @@
-    # Sanity check.
-    if (!defined($job)) {
-new job
-new job
+a new process
+a new process
-    }
-
-    # Spawn the job.
-
-
-
+
+
+
+
+
+
+
+
+
-
-    # Run the job.
-    $job->run($timeout);
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-    # Return the modified object state.
@@ -251 +484 @@
-
-1;
+
+#######################################################################
+# Additional Module Documentation                                     #
+#######################################################################
+
+__END__
+
+=head1 BUGS & ASSUMPTIONS
+
+This package will only run on Win32 platforms.  Furthermore, it has
+only been tested to work reliably within a Cygwin environment.
+
+In a nutshell, this object is nothing more than a blessed anonymous
+reference to a hashtable, where (key => value) pairs are defined in
+the L<DEFAULT PARAMETER LIST>, as well as fed via the new() function
+during object initialization.  As such, this package does B<not>
+perform any rigorous B<data validation> prior to accepting any new
+or overriding (key => value) pairs.
+
+However, additional links can be fed to any FF driver at any time, by
+simply adding new hashtable entries to the B<links_to_visit> hashtable
+within the B<$object>.
+
+For example, if you wanted to add the URL "http://www.mitre.org"
+to the FF driver B<$object>, simply use the following code:
+
+  $object->{links_to_visit}->{'http://www.mitre.org'} = 1;
+
+In general, the FF driver does B<not> know how many links it will
+ultimately end up browsing to, until it conducts an exhaustive
+spider of all initial URLs supplied.  As such, expect the output
+of $object->status() to change significantly, upon each
+$object->drive() iteration.
+
+For example, if at one given point, the status of B<percent_complete>
+is 30% and then this value drops to 15% upon another iteration, then
+this means that the total number of links to drive to has greatly
+increased.
+
+Lastly, we assume that the Mozilla Firefox browser has
+been preconfigured to B<not cache any data>.  This ensures the browser
+will render the most recent version of the content hosted at each URL.
+
+=head1 SEE ALSO
+
+L<HoneyClient::Agent::Driver>
+
+L<HoneyClient::Agent::Driver::Browser>
+
+L<HoneyClient::Agent::Driver::Browser::IE>
+
+L<http://www.honeyclient.org/trac>
+
+=head1 REPORTING BUGS
+
+L<http://www.honeyclient.org/trac/newticket>
+
+=head1 AUTHORS
+
+Kathy Wang, E<lt>knwang@mitre.orgE<gt>
+
+Thanh Truong, E<lt>ttruong@mitre.orgE<gt>
+
+Darien Kindlund, E<lt>kindlund@mitre.orgE<gt>
+
+Brad Stephenson, E<lt>stephenson@mitre.orgE<gt>
+
+=head1 COPYRIGHT & LICENSE
+
+Copyright (C) 2007 The MITRE Corporation.  All rights reserved.
+
+This program 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, using version 2
+of the License.
+
+This program 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 this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301, USA.
+
+
+=cut
+

honeyclient/branches/exp/kindlund-firefox/t/honeyclient_agent_driver_browser_ff.t

@@ -7 +7 @@
-
-
+# =begin testing
+{
+# Make sure Log::Log4perl loads
+BEGIN { use_ok('Log::Log4perl', qw(:nowarn))
+        or diag("Can't load Log::Log4perl package. Check to make sure the package library is correctly listed within the path.");
+       
+        # Suppress all logging messages, since we need clean output for unit testing.
+        Log::Log4perl->init({
+            "log4perl.rootLogger"                               => "DEBUG, Buffer",
+            "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer",
+            "log4perl.appender.Buffer.min_level"                => "fatal",
+            "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout",
+            "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n",
+        });
+}
+require_ok('Log::Log4perl');
+use Log::Log4perl qw(:easy);
+
+# Make sure HoneyClient::Util::Config loads.
+BEGIN { use_ok('HoneyClient::Util::Config', qw(getVar))
+        or diag("Can't load HoneyClient::Util::Config package.  Check to make sure the package library is correctly listed within the path."); 
+
+        # Suppress all logging messages, since we need clean output for unit testing.
+        Log::Log4perl->init({
+            "log4perl.rootLogger"                               => "DEBUG, Buffer",
+            "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer",
+            "log4perl.appender.Buffer.min_level"                => "fatal",
+            "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout",
+            "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n",
+        });
+        
+}
+require_ok('HoneyClient::Util::Config');
+can_ok('HoneyClient::Util::Config', 'getVar');
+use HoneyClient::Util::Config qw(getVar);
+
+# Make sure the module loads properly, with the exportable
+# functions shared.
+BEGIN { use_ok('HoneyClient::Agent::Driver::Browser::FF') or diag("Can't load HoneyClient::Agent::Driver::Browser::FF package.  Check to make sure the package library is correctly listed within the path."); }
+require_ok('HoneyClient::Agent::Driver::Browser::FF');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'new');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'drive');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'isFinished');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'next');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'status');
+can_ok('HoneyClient::Agent::Driver::Browser::FF', 'getNextLink');
+use HoneyClient::Agent::Driver::Browser::FF;
+
+# Suppress all logging messages, since we need clean output for unit testing.
+Log::Log4perl->init({
+    "log4perl.rootLogger"                               => "DEBUG, Buffer",
+    "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer",
+    "log4perl.appender.Buffer.min_level"                => "fatal",
+    "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout",
+    "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n",
+});
+
+# Make sure Win32::Job loads.
+BEGIN { use_ok('Win32::Job') or diag("Can't load Win32::Job package.  Check to make sure the package library is correctly listed within the path."); }
+require_ok('Win32::Job');
+use Win32::Job;
+
+# Make sure ExtUtils::MakeMaker loads.
+BEGIN { use_ok('ExtUtils::MakeMaker', qw(prompt)) or diag("Can't load ExtUtils::MakeMaker package.  Check to make sure the package library is correctly listed within the path."); }
+require_ok('ExtUtils::MakeMaker');
+can_ok('ExtUtils::MakeMaker', 'prompt');
+use ExtUtils::MakeMaker qw(prompt);
+}
+
+
+
+# =begin testing
+{
+# Generate a notice, to clarify our assumptions.
+diag("");
+diag("About to run basic FF-specific browser tests.");
+diag("Note: These tests *require* network connectivity and");
+diag("*expect* FF to be installed at the following location.");
+diag("");
+
+my $processExec = getVar(name      => "process_exec",
+                         namespace => "HoneyClient::Agent::Driver::Browser::FF");
+my $processName = getVar(name      => "process_name",
+                         namespace => "HoneyClient::Agent::Driver::Browser::FF");
+
+diag("Process Name:\t\t'" . $processName . "'");
+diag("Process Location:\t'" . $processExec . "'");
+diag("");
+diag("If FF is installed in a different location or has a different executable name,");
+diag("then please answer *NO* to the next question and update your etc/honeyclient.xml");
+diag("file, changing the 'process_name' and 'process_exec' elements in the");
+diag("<HoneyClient/><Agent/><Driver/><Browser/><FF/> section.");
+diag("");
+diag("Then, once updated, re-run these tests.");
+diag("");
+
+my $question;
+$question = prompt("# Do you want to run these tests?", "yes");
+if ($question !~ /^y.*/i) {
+    exit;
+}
+
+my $ie = HoneyClient::Agent::Driver::Browser::FF->new(test => 1);
+is($ie->{test}, 1, "new(test => 1)") or diag("The new() call failed.");
+isa_ok($ie, 'HoneyClient::Agent::Driver::Browser::FF', "new(test => 1)") or diag("The new() call failed.");
+
+diag("");
+diag("About to drive FF to a specific website for *exactly* " . $ie->{timeout} . " seconds.");
+diag("Note: Please do *NOT* close the browser manually; the test code should close it automatically.");
+diag("");
+
+$question = prompt("# Which website should FF browse to?", "http://www.google.com");
+$ie->drive(url => $question);
+
+diag("");
+$question = prompt("# Did FF properly render the page and automatically exit?", "yes");
+if ($question !~ /^y.*/i) {
+    diag("");
+    diag("Check your network connectivity and verify that you can manually browse this page in FF.");
+    diag("Then, re-run these tests.");
+    diag("");
+    diag("If the tests still do not work, please submit a ticket to:");
+    diag("http://www.honeyclient.org/trac/newticket");
+    diag("");
+    fail("The drive() call failed.");
+}
+}
-
-