From cc7f83a623c3a8ae20d9c00e635f3f392dd2bb18 Mon Sep 17 00:00:00 2001
From: Graham Knop <haarg@haarg.org>
Date: Fri, 11 Jun 2010 00:41:24 -0500
Subject: [PATCH] add documentation for new test modules

---
 t/lib/WebGUI/Test/MailServer.pm | 46 +++++++++++++++++++++------------
 t/lib/WebGUI/Test/MockAsset.pm  | 28 +++++++++++++++++++-
 2 files changed, 56 insertions(+), 18 deletions(-)

diff --git a/t/lib/WebGUI/Test/MailServer.pm b/t/lib/WebGUI/Test/MailServer.pm
index dad3bf3a5..6021e8cf6 100644
--- a/t/lib/WebGUI/Test/MailServer.pm
+++ b/t/lib/WebGUI/Test/MailServer.pm
@@ -20,6 +20,32 @@ Package WebGUI::Test::MailServer
 
 Routines for testing mail sending in WebGUI
 
+=head1 SUBROUTINES
+
+=head2 test_smtp ( $session, $testSub )
+
+Sets up a SMTP server and runs a test sub against it.  The test sub will be called with a callback sub as a parameter.  Calling that callback will return a hash ref with four keys.
+
+=over 8
+
+=item to
+
+Contains an array of addresses the message was sent to.
+
+=item from
+
+Contains the address the message was sent from.
+
+=item contents
+
+Contains the raw contents of the mail message.
+
+=item parsed
+
+Contains the mail message as a L<MIME::Entity> object.
+
+=back
+
 =cut
 
 use strict;
@@ -39,6 +65,7 @@ my $smtpdPid;
 my $smtpdStream;
 my $smtpdSelect;
 
+
 sub test_smtp {
     my $session = shift;
     my $testSub = shift;
@@ -71,7 +98,7 @@ sub _setup_server {
     my $lib_path = catdir( dirname(__FILE__), (updir) x 2 );
     my @command_line = (
         $^X, "-I$lib_path", '-M' . __PACKAGE__,
-        '-e' . __PACKAGE__ . '::run_server(@ARGV)', $host, $port,
+        '-e' . __PACKAGE__ . '::_run_server(@ARGV)', $host, $port,
     );
 
     $smtpdPid = open $smtpdStream, '-|', @command_line
@@ -102,22 +129,7 @@ sub _shutdown_server {
     }
 }
 
-=head2 getMail ( )
-
-Read a sent mail from the prepared mail server (L<prepareMailServer>)
-
-=cut
-
-sub getMail {
-    my $json;
-
-    if ($smtpdSelect->can_read(5)) {
-        $json = <$smtpdStream>;
-    }
-    return from_json( $json );
-}
-
-sub run_server {
+sub _run_server {
     my ($host, $port) = @_;
     my $server  = Net::SMTP::Server->new( $host, $port );
     local $| = 1;
diff --git a/t/lib/WebGUI/Test/MockAsset.pm b/t/lib/WebGUI/Test/MockAsset.pm
index 2a670dc36..6d22f971b 100644
--- a/t/lib/WebGUI/Test/MockAsset.pm
+++ b/t/lib/WebGUI/Test/MockAsset.pm
@@ -18,7 +18,33 @@ Package WebGUI::Test::MockAsset
 
 =head1 DESCRIPTION
 
-Utility module for making testing in WebGUI easier.
+Creates fake WebGUI::Asset objects and sets them up to be returned by WebGUI::Asset's normal constructors.
+
+=head1 METHODS
+
+=head2 new ( [ $class ], [ $id ] )
+
+Creates a new mock asset.  If not specified, the class will default to L<WebGUI::Asset>.  In addition to the methods listed, it will also include all of the methods from L<Test::MockObject>.  The object will automatically be cleaned up and will no longer be returned once it goes out of scope.
+
+=head2 mock_id ( $assetId, [ $asset_or_sub ] )
+
+As an object method, sets the asset ID for the object, and also sets the asset to be returned for that ID.
+
+As a class method, also accepts a second parameter.  If the second parameter is a sub, it will be called when the given asset ID is requested.  For any other type, the given object will be returned.
+
+=head2 unmock_id ( [ $assetId ] )
+
+As an object method, the mocking set up for the object by mock_id will be removed.
+
+As a class method, mocking will be removed for the given asset ID.
+
+=head2 mock_url ( $assetUrl, [ $asset_or_sub ] )
+
+Works the same as mock_id, except for asset URLs instead of IDs.
+
+=head2 unmock_url ( [ $assetUrl ] )
+
+Works the same as unmock_id, except for asset URLs instead of IDs.
 
 =cut