[Jifty-commit] r3994 - in Test-WWW-Declare: lib/Test/WWW

[jifty-commit at lists.jifty.org]

Author: sartak
Date: Sun Aug 26 20:03:08 2007
New Revision: 3994

Modified:
   Test-WWW-Declare/   (props changed)
   Test-WWW-Declare/lib/Test/WWW/Declare.pm

Log:
 r37425 at onn:  sartak | 2007-08-26 20:00:00 -0400
 More documentation, still a lot of stubs


Modified: Test-WWW-Declare/lib/Test/WWW/Declare.pm
==============================================================================
--- Test-WWW-Declare/lib/Test/WWW/Declare.pm	(original)
+++ Test-WWW-Declare/lib/Test/WWW/Declare.pm	Sun Aug 26 20:03:08 2007
@@ -35,7 +35,7 @@
 =head1 SYNOPSIS
 
     use Test::WWW::Declare tests => 3;
-    use Your::Web::App;
+    use Your::Web::App::Test;
 
     session 'testuser' => run {
         flow 'log in and out' => check {
@@ -62,10 +62,77 @@
 likely there will be many more failures. This module aims to alleviate this
 problem, as well as provide a nicer interface to L<Test::WWW::Mechanize>.
 
-The central idea is that of flow. Each flow is a sequence of commands ("fill in
-this form") and assertions ("content should contain 'testuser'"). If any of these
-commands or assertions fail then the flow is aborted. Only that one failure is
-reported to the user.
+The central idea is that of "flow". Each flow is a sequence of commands ("fill
+in this form") and assertions ("content should contain 'testuser'"). If any of
+these commands or assertions fail then the flow is aborted. Only that one
+failure is reported to the test harness and user. Flows may also contain other
+flows. If an inner flow fails, then the outer flow fails as well.
+
+=head1 FLOWS AND SESSIONS
+
+=head2 session NAME => run { CODE }
+
+Sessions are a way of associating a set of flows with a L<WWWW::Mechanize>
+instance. A session is mostly equivalent with a user interacting with your web
+app.
+
+Within a session, every command (C<get>, C<click link>, etc) is operating on
+that session's L<WWW::Mechanize> instance. You may have multiple sessions in
+one test file. Two sessions with the same name are in fact the same session.
+This lets you write code like the following, simplified slightly:
+
+    session 'first user' => run {
+        get "$URL/give?task=1&victim=other";
+        session 'other user' => run {
+            get "$URL/tasks";
+            content should match qr/task 1/;
+
+            # this is the same session/mech as the outermost 'first user'
+            session 'first user' => run {
+                get "$URL/tasks";
+                content shouldnt match qr/task 1/;
+            };
+        };
+    };
+
+=head2 flow NAME => check { CODE }
+
+A flow encompasses a single test. As described above, each flow is a sequence
+of commands, assertions, and other flows. If any of the components of a flow
+fail, the rest of the flow is aborted and one or more test failures are
+reported to the test harness.
+
+=head1 COMMANDS
+
+=head2 get URL
+
+=head2 click button
+
+=head2 click href
+
+=head2 follow_link
+
+=head2 fill form NAME => {FIELD1 => VALUE1, FIELD2 => VALUE2}
+
+=head1 ASSERTIONS
+
+Every assertion has two parts: a subject and a verb.
+
+=head2 SUBJECTS
+
+=head3 content
+
+=head3 title
+
+=head2 VERBS
+
+=head3 should(nt) (caselessly) match REGEX
+
+=head3 should(nt) (caselessly) contain STRING
+
+=head3 should(nt) (caselessly) lack STRING
+
+=head3 should(nt) (caselessly) equal STRING
 
 =cut