Changeset 1647

Timestamp:

09/02/06 06:55:07

Author:

mark

Message:

r12@travis: mark | 2006-09-01 20:54:58 +0100

added some documentation to the Test

Base extention

trunk/plagger/t/TestPlagger.pm

@@ -24 +24 @@
-}
-
+=item test_requires
+
+Checks to see if the module can be loaded.
+
+   test_requires("Your::Momma");
+   test_requires("Your::Momma",3.141); # version 3.141 or later
+
+If this fails rather than failing tests this B<skips all tests>.
+
+=cut
+
-sub test_requires() {
-    my($mod, $ver) = @_;
@@ -43 +54 @@
-}
-
+=item has_network($spec)
+
+Returns true if and only if the specified port can be established.  The
+spec should be of the form:
+
+  hostname:port
+
+e.g.
+
+  plagger.org:80
+
+This function always returns false immediatly without connecting to the
+network if the enviroment varible C<NO_NETWORK> has been set.
+
+=cut
+
-sub has_network() {
-    my $host = shift;
@@ -52 +79 @@
-}
-
+=item test_requires_network
+
+This function skips all tests if the network is not reachable, e.g.
+
+  # can I reach google's web site?
+  test_requires_network();
+  
+  # can I reach plagger's web site?
+  test_requires_network("plagger.org")
+  
+  # can I reach a different port?
+  test_requires_network("gmail.com:443");
+
+=cut
+
-sub test_requires_network() {
-    my $host = shift || 'www.google.com:80';
@@ -60 +102 @@
-    }
-}
+
+=item test_requires_command($command)
+
+This function skips all tests if the given command
+doesn't exist in your path (i.e. in the dirs in the PATH enviroment
+variable.)
+
+=cut
-
-sub test_requires_command() {
@@ -71 +121 @@
-}
-
+=item test_plugin_deps
+
+This function skips all tests if the module's requirements
+(modules, versions, platforms, bundles) aren't installed.
+
+If you pass an argument then it will check the requirement
+for that module:
+
+  # this will check the Foo-Bar.yaml file for deps
+  test_plugin_deps("Foo::Bar");
+
+Called with no arguments it works out magically the name of
+the plugin based on the directory the test file is located
+in.
+
+   # in the Foo-Bar/wobble.t file
+   # this will check the Foo-Bar.yaml file for deps   
+   test_plugin_deps();
+  
+The requirements are defined in YAML files located
+in the C<deps> directory inside the Plagger directory.  A typical
+YAML file looks like this:
+
+  name: Publish::Speech::MacOSX
+  author: Ryo Okamoto
+  platform: darwin
+  depends: 
+    Mac::Files: 0
+    Mac::Speech: 0
+
+Or
+
+  name: Subscription::Bookmarks::Mozilla
+  author: youpy
+  bundles:
+    - Subscription::XPath
+
+=cut
+
-sub test_plugin_deps() {
-    my($mod, $no_warning) = @_;
@@ -98 +187 @@
-}
-
+=item run_eval_expected
+
+Add a new test run across all blocks to check that
+the expected blocks can be evaled succesfully.  During
+these evaluations the expected input is availible from
+C<$context>.
+
+One extra test failure will happen per block that's expected
+output throws an error when evaluated.  No successes are
+generated by this code, but the expected code may in
+turn generate many sucesses or failures.
+
+=cut
+
-sub run_eval_expected {
-    run {
-        my $block = shift;
+        
+        # context is being pulled out here so that
+        # the eval box can see it
-        my $context = $block->input; # it's not always true
+        
-        eval $block->expected;
-        fail $@ if $@;
@@ -107 +214 @@
-}
-
+=item run_eval_expected_with_capture
+
+Add new test run across all blocks to check that
+the expected blocks can be evaled succesfully.  During
+these evaluations the expected input is availible from
+C<$context>, and warnings created by the filters
+are avalible from C<$warnings>.
+
+=cut
+
-sub run_eval_expected_with_capture {
-    filters_delay;
-    for my $block (blocks) {
+      
+        # capture all the warnings from the filters
+        # this is often used in the tests as a way to find
+        # out what has happened (e.g. the Growl plugin)
-        my $warning;
-        {
@@ -115 +236 @@
-            $block->run_filters;
-        }
+        
+        # context is being pulled out here so that
+        # the eval box can see it
-        my $context = $block->input;
+        
-        eval $block->expected;
-        fail $@ if $@;
-    }
-}
+
+=item slurp_file($filename)
+
+Returns the contents of the file, as a single scalar
+
+=cut
-
-sub slurp_file() {