Update User Guide

FitNesseRoot/FitNesse/UserGuide/TestHistory/content.txt

@@ -18,4 +18,5 @@ There are buttons at the top of the ''Test History'' page that allow you to purg
 When viewing the history for a page, you can select any two test results by clicking in their checkboxes.  Then, if you click the ''Compare'' button, you will be shown the two test results side-by-side along with an indicator that tells you if the results are identical or not.
 
 Only tests can be compared this way.  Suites cannot.
-!note !style_blue(This is an ''alpha'' level feature.  Lots more goodies coming soon.)
+
+Notice that the comparison is pretty smart.  It tries to line up the two tests on a table-by-table basis.  It can detect if tables have been inserted or deleted.  The % code that you see on the left is just the match score for the tables.

FitNesseRoot/FitNesse/UserGuide/TestSuites/CrossReferenceSuites/content.txt

@@ -0,0 +1,11 @@
+!3 Suite Cross References
+Sometimes you want to compose a test suite from test pages that are in many different modules, subsystems, or features.  For example you might want a test suite that lists all the test pages for the current iteration, or you might want a test suite that lists all the currently passing tests, or you may want to create a test suite for all the quickly executing tests, and another for all the slow tests.
+
+To do this you can use the [['''!-!see-!'''][<UserGuide.MarkupCrossReference]] command in a test suite.  Any test pages referenced by '''!-!see-!''' on a suite page will be executed as part of that suite.
+
+The suite page might look like this:
+{{{
+!see .MyProject.MyFeature.IterationOne.StoryOne.TestCaseOne
+!see .MyProject.MyFeature.IterationTwo.StoryTwelve.TestCaseThirteen
+...
+}}}

FitNesseRoot/FitNesse/UserGuide/TestSuites/CrossReferenceSuites/properties.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<properties>
+	<Edit>true</Edit>
+	<Files>true</Files>
+	<Properties>true</Properties>
+	<RecentChanges>true</RecentChanges>
+	<Refactor>true</Refactor>
+	<Search>true</Search>
+	<Versions>true</Versions>
+	<WhereUsed>true</WhereUsed>
+</properties>

FitNesseRoot/FitNesse/UserGuide/TestSuites/SubWikiSuites/content.txt

@@ -0,0 +1,22 @@
+!3 SubWiki: the Most Convenient Way to Organize TestSuites
+
+[[!-SubWikis-!][<UserGuide.SubWiki]] are convenient for creating a hierarchical structure for your suite of tests.  You can put test pages below subsystems and/or features.  You can organize ClassPath and variable definitions in the parent pages.  When you hit the ''Suite'' button on a parent page, all the descendant pages that have the ''Test'' property will be executed as part of the suite.  FitNesse's own set of acceptance tests is organized this way.  See <.FitNesse.SuiteAcceptanceTests.
+
+You can use the hierarchy to organize your test by Iteration, or by Feature, or by any other scheme you like.  The acceptance tests for FitNesse are organized by feature.  Other teams organize by iteration.  A typical hierarchy by iteration might look like this:
+
+{{{
+MyProject
+  IterationOne
+    StoryOne
+      TestCaseOne
+      TestCaseTwo
+      ...
+    StoryTwo
+      TestCaseOne
+      TestCaseTwo
+      ...
+    ...
+  ...
+}}}
+Of course you'd use better names than that.  You could then mark the project, iteration, and story pages as suites.  If you hit the suite button on the project page it would execute every test in the project.  If you hit the suite button on MyProject.IterationOne.StoryTwo it would execute only those tests in the second story of the first iteration.
+

FitNesseRoot/FitNesse/UserGuide/TestSuites/SubWikiSuites/properties.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<properties>
+	<Edit>true</Edit>
+	<Files>true</Files>
+	<Properties>true</Properties>
+	<RecentChanges>true</RecentChanges>
+	<Refactor>true</Refactor>
+	<Search>true</Search>
+	<Versions>true</Versions>
+	<WhereUsed>true</WhereUsed>
+</properties>

FitNesseRoot/FitNesse/UserGuide/TestSuites/SuiteQuery/content.txt

@@ -0,0 +1,22 @@
+A Suite Query is a regular page with the ''Suite'' property set so that it has a ''Suite'' button.  On that page are one or more tables that specify the query.  The page you are looking at right now, is a suite query.  Notice the two tables below.  They specify the query.  You can run the query (and the tests) by hitting the ''Suite'' button.
+
+!|Suite|
+|Page|FitNesse.SuiteAcceptanceTests|
+|Content|[Bb]ug|
+
+!|Suite|
+|Page|FitNesse.SuiteAcceptanceTests|
+|Title|Import|
+
+Each of these tables is called a ''Suite Specification''.  A ''Suite Specification'' is always a table whose first cell is the word ''Suite'', capitalized as shown.  The other rows must each have two cells, and the first cell in each row must be either ''Page'', ''Content'' or ''Title''.  
+ * ''Page'' - The second cell in the ''Page'' row is the fully qualified page name that forms the root of the search.  The search will proceed only with descendants of this page.
+ * ''Title'' - The second cell in the ''Title'' row specifies a regular expression to be used to match a page name. Every page in the search whose name matches that regular expression will be included in the suite.
+ * ''Content'' - The second cell in the ''Content'' row specifies a regular expression to be used to match the contents of a page.  Every page in the search whose content contains a string that matches that regular expression will be included in the suite.
+
+Every ''Suite Specification'' table represents the ''Intersection'' of the ''Page'', ''Title'', and ''Content''.  Thus, they form an ''AND'' operation.  Only those pages that are descended from ''Page'' and match ''Title'' and match ''Content'' will be in the suite.  Of course, if either ''Title'' or ''Content'' are omitted (as above) then they are ignored.  
+
+If you have multiple ''Suite Specification'' tables, then the suite will be the ''disjuction'' (The logical OR) of all of them.  
+
+!note The regular expressions conform to the Java library. 
+
+

FitNesseRoot/FitNesse/UserGuide/TestSuites/SuiteQuery/properties.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0"?>
+<properties>
+	<Edit>true</Edit>
+	<Files>true</Files>
+	<Properties>true</Properties>
+	<RecentChanges>true</RecentChanges>
+	<Refactor>true</Refactor>
+	<Search>true</Search>
+	<Suite>true</Suite>
+	<Versions>true</Versions>
+	<WhereUsed>true</WhereUsed>
+</properties>

FitNesseRoot/FitNesse/UserGuide/TestSuites/SuiteSetUpAndSuiteTearDown/content.txt

@@ -0,0 +1,6 @@
+!3 !-SetUp-! and !-TearDown-!
+Sometimes you will need to delete a test database at the end of each test in a suite, or create an empty database at the beginning of each test.  Operations like this can be performed by writing special fixtures that perform these functions in their constructors.  These fixtures can then be invoked in the '''!-SetUp-!''' and '''!-TearDown-!''' pages of the suite.  See <UserGuide.SpecialPages.
+
+To perform operations at the beginning or end of an entire suite, rather than for each test, define the operations on pages named '''!-SuiteSetUp-!''' and '''!-SuiteTearDown-!'''.
+
+!-SuiteSetUp and SuiteTearDown-! are associated with a test page by "Uncle Inheritance" as described in <UserGuide.SpecialPages.  A suite has many different test pages, and it is possible that some will have different !-SuiteSetUp and SuiteTearDown-! pages.  Therefore tests in a suite are organized into groups that share the same !-SuiteSetup and SuiteTearDown-! pages.  The tests are executed in those groups, with the !-SuiteSetUp-! preceding them, and the !-SuiteTearDown-! following them.   

FitNesseRoot/FitNesse/UserGuide/TestSuites/SuiteSetUpAndSuiteTearDown/properties.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0"?>
+<properties>
+	<Edit>true</Edit>
+	<Files>true</Files>
+	<Properties>true</Properties>
+	<RecentChanges>true</RecentChanges>
+	<Refactor>true</Refactor>
+	<Search>true</Search>
+	<Suite>true</Suite>
+	<Versions>true</Versions>
+	<WhereUsed>true</WhereUsed>
+</properties>

FitNesseRoot/FitNesse/UserGuide/TestSuites/TagsAndFilters/content.txt

@@ -0,0 +1,26 @@
+!3 Suite Tags
+
+The properties page offers a field labeled ''Tags'' where you can enter a comma-separated list of keywords. These keywords can then be used as targets for searching and executing those tests.
+
+!3 Searching for tags
+If you hit the !style_code(Search) button, You will see a form that allows you to search for pages that certain attributes or tags.  For example, you can search for all subpages that have the !style_code(Suite) property set, or all pages that are read-only, or that have the !style_code(Edit) button displayed.  Most importantly, you can search for pages marked with tags.
+
+If you put a comma separated list of tags into the !style_code(Tags) input box, and then search, you will be shows a list of pages that are marked with any of those tags.  Notice that if the pages are tests or suites, they have a link next to them that allows you to execute them.   Also, look at the bottom and see the useful text that can be copied and pasted onto other pages in order to repeat the search or test the resulting pages.
+
+Using these tools, you can easily tag some tests as "smoke" tests, or "critical", or "fast".  You can find all the "smoke" tests and run them, etc.
+
+!3 Using tags to select which tests to run.
+The easiest way to execute tagged tests is to search for the tags as described in the previous section.  Sometimes, though, you'd like to execute the tests via a RESTful service, or from the command line (using TestRunner).
+You can execute the tests that match a tag by using the !style_code(suiteFilter) query parameter with a suite url like this:
+!style_code(!-http://<host>:<port>/<suite path and test name>?responder=suite&suiteFilter=smoke,critical-!)
+
+If you want to execute all the tests in a suite except those with a particular tag (eg !-NotRunningOnHudson-!) then you use the !style_code(excludeSuiteFilter) query parameter:  For example:
+!style_code(!-http://<host>:<port>/<suite path and test name>?responder=suite&excludeSuiteFilter=NotRunningOnHudson-!)
+
+Typically, you will need only a few of such filtered suites, so it is suggested to build a link on the front page or so which contains the respective suite filter parameters. (If you simply click on the ''Suites'' button to run a suite, the !-suiteFilter-! is not set, so all tests in the respective subwiki are run.)
+
+!3 Executing test starting with a certain test.
+Sometimes half the suite will run okay, but after a point all tests will start failing.   In that case you can save time re-running the tests by stating which test you would like to start with.   For instance:
+!style_code(!-http://<host>:<port>/<suite path and test name>?responder=suite&startTest=TestTwo-!) will run all tests coming after !-TestTwo-!
+
+Remember, that the order tests run is alphabetical.  So in the above example, !-TestThree-! will not run because !-TestTwo-! actually comes after !-TestThree-!

FitNesseRoot/FitNesse/UserGuide/TestSuites/TagsAndFilters/properties.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<properties>
+	<Edit>true</Edit>
+	<Files>true</Files>
+	<Properties>true</Properties>
+	<RecentChanges>true</RecentChanges>
+	<Refactor>true</Refactor>
+	<Search>true</Search>
+	<Versions>true</Versions>
+	<WhereUsed>true</WhereUsed>
+</properties>

FitNesseRoot/FitNesse/UserGuide/TestSuites/content.txt

@@ -1,50 +1,13 @@
 !1 Suites of Tests
-A suite is a collection of test pages that can all be run together, and whose results are then collected for you on a single results page. For an example of a Suite of tests, see TriviaGameUserStories.
+A suite is a collection of test pages that can all be run together, and whose results are then collected for you on a single results page, and in [[Test History][<UserGuide.TestHistory]]. For an example of a Suite of tests, see .FitNesse.SuiteAcceptanceTests.
 
 !3 Setting up a '''Suite''' page.
-You can run all the test pages in a sub-wiki by setting the "Suite" property of a page (see [[Page Properties][PageProperties]]).  That page will then include a "Suite" button that will execute all the test pages in that hierarchy.
+To create a Suite page you set the "Suite" property of that page (see [[Page Properties][PageProperties]]).  That page will then include a "Suite" button that will execute all the test pages in that hierarchy.
 
-!3 !-SetUp-! and !-TearDown-!
-Sometimes you will need to delete a test database at the end of each test in a suite, or create an empty database at the beginning of each test.  Operations like this can be performed by writing special fixtures that perform these functions in their constructors.  These fixtures can then be invoked in the '''!-SetUp-!''' and '''!-TearDown-!''' pages of the suite.  See <UserGuide.SpecialPages.
+!3 Composing Suites.
+There are several ways to compose a suite.  You can convert a whole subwiki into a suite.  You can list individual pages using cross references, and you can create queries that search all the pages for matches.
 
-To perform operations at the beginning or end of an entire suite, rather than for each test, define the operations on pages named '''!-SuiteSetUp-!''' and '''!-SuiteTearDown-!'''.
-
-!3 SubWiki: the Best Way to Organize TestSuites
-
-[[!-SubWikis-!][SubWiki]] are convenient for creating a hierarchical structure for your suite of tests.  You can put test pages below subsystems and/or features.  You can organize ClassPath and variable definitions in the parent pages.
-
-!3 Suite Cross References
-Sometimes you want to compose a test suite from test pages that are in many different modules, subsystems, or features.  For example you might want a test suite that lists all the test pages for the current iteration, or you might want a test suite that lists all the currently passing tests, or you may want to create a test suite for all the quickly executing tests, and another for all the slow tests.
-
-To do this you can use the [['''!-!see-!'''][MarkupCrossReference]] command in a test suite.  Any test pages referenced by '''!-!see-!''' on a suite page will be executed as part of that suite.
-
-!3 Suite Tags
-There is an alternative to the !-!see-! command to aggregate some tests into a suite: the so-called suite tags.
-
-The properties page offers a field labeled ''Tags'' where you can enter a comma-separated list of keywords. These keywords can then be used as targets for searching and executing those tests.
-
-!3 Searching for tags
-If you hit the !style_code(Search) button, You will see a form that allows you to search for pages that certain attributes or tags.  For example, you can search for all subpages that have the !style_code(Suite) property set, or all pages that are read-only, or that have the !style_code(Edit) button displayed.  Most importantly, you can search for pages marked with tags.
-
-If you put a comma separated list of tags into the !style_code(Tags) input box, and then search, you will be shows a list of pages that are marked with any of those tags.  Notice that if the pages are tests or suites, they have a link next to them that allows you to execute them.   Also, look at the bottom and see the useful text that can be copied and pasted onto other pages in order to repeat the search or test the resulting pages.
-
-Using these tools, you can easily tag some tests as "smoke" tests, or "critical", or "fast".  You can find all the "smoke" tests and run them, etc.
-
-!3 Using tags to select which tests to run.
-The easiest way to execute tagged tests is to search for the tags as described in the previous section.  Sometimes, though, you'd like to execute the tests via a RESTful service, or from the command line (using TestRunner).
-You can execute the tests that match a tag by using the !style_code(suiteFilter) query parameter with a suite url like this:
-!style_code(!-http://&lt;host>:&lt;port>/&lt;suite path and test name>?responder=suite&suiteFilter=smoke,critical-!)
-
-If you want to execute all the tests in a suite except those with a particular tag (eg !-NotRunningOnHudson-!) then you use the !style_code(excludeSuiteFilter) query parameter:  For example:
-!style_code(!-http://&lt;host>:&lt;port>/&lt;suite path and test name>?responder=suite&excludeSuiteFilter=NotRunningOnHudson-!)
-
-Typically, you will need only a few of such filtered suites, so it is suggested to build a link on the front page or so which contains the respective suite filter parameters. (If you simply click on the ''Suites'' button to run a suite, the !-suiteFilter-! is not set, so all tests in the respective subwiki are run.)
-
-!3 Executing test starting with a certain test.
-Sometimes half the suite will run okay, but after a point all tests will start failing.   In that case you can save time re-running the tests by stating which test you would like to start with.   For instance:
-!style_code(!-http://&lt;host>:&lt;port>/&lt;suite path and test name>?responder=suite&startTest=TestTwo-!) will run all tests coming after !-TestTwo-!
-
-Remember, that the order tests run is alphabetical.  So in the above example, !-TestThree-! will not run because !-TestTwo-! actually comes after !-TestThree-!
+!contents -R2 -g
 
 !3 Getting suite results in XML rather than HTML format.
-Finally, if you want the results in xml, simply put !style_code(&format=xml).
+If you want the results in xml, simply put !style_code(&format=xml) in the url.

FitNesseRoot/FitNesse/UserGuide/TestSuites/properties.xml

@@ -1,7 +1,14 @@
 <?xml version="1.0"?>
 <properties>
+	<Edit/>
 	<Files/>
+	<Help/>
+	<Normal/>
+	<Properties/>
 	<RecentChanges/>
+	<Refactor/>
+	<Suites/>
+	<Versions/>
 	<WhereUsed/>
 	<saveId>1238174950604</saveId>
 	<ticketId>-8493028553090165617</ticketId>

FitNesseRoot/RecentChanges/content.txt

@@ -1,3 +1,10 @@
+|FitNesse.UserGuide.TestSuites||15:59:39 Tue, Aug 18, 2009|
+|FitNesse.UserGuide.TestSuites.SuiteQuery||15:57:54 Tue, Aug 18, 2009|
+|FitNesse.UserGuide.TestSuites.TagsAndFilters||15:38:03 Tue, Aug 18, 2009|
+|FitNesse.UserGuide.TestSuites.SubWikiSuites||15:36:58 Tue, Aug 18, 2009|
+|FitNesse.UserGuide.TestSuites.SuiteSetUpAndSuiteTearDown||15:30:39 Tue, Aug 18, 2009|
+|FitNesse.UserGuide.TestSuites.CrossReferenceSuites||15:20:08 Tue, Aug 18, 2009|
+|FitNesse.UserGuide.TestHistory||14:49:30 Tue, Aug 18, 2009|
 |FitNesse.SuiteAcceptanceTests.SuiteTestRunnerTests||14:01:30 Tue, Aug 18, 2009|
 |FitNesse.SuiteAcceptanceTests.SuiteTestRunnerTests.TestRunnerGeneratesXmlReports||13:44:49 Tue, Aug 18, 2009|
 |FitNesse.SuiteAcceptanceTests.SuiteTestRunnerTests.TestRunnerExitValue||12:57:23 Tue, Aug 18, 2009|
@@ -72,7 +79,6 @@
 |FitNesse.SuiteAcceptanceTests.SuiteTestRunnerTests.TestRunnerVerboseOutput||13:29:25 Tue, Jul 28, 2009|
 |JunkPage.ExceptionTest||09:48:08 Sat, Jul 25, 2009|
 |FitNesse.UserGuide.RestfulServices||17:44:22 Thu, Jul 09, 2009|
-|FitNesse.UserGuide.TestHistory||17:39:37 Thu, Jul 09, 2009|
 |FitNesse.UserGuide.DownloadingAndInstallingFitNesse||14:50:07 Wed, Jul 08, 2009|
 |FitNesse.UserGuide||14:43:23 Wed, Jul 08, 2009|
 |FitNesse.SuiteAcceptanceTests.SuiteSlimTests.ScenarioLibraryTestSuite.BrotherScenarioLibraryIsIncluded||15:41:42 Wed, Jul 22, 2009|
@@ -92,9 +98,3 @@
 |FitNesse.SuiteAcceptanceTests.SuiteResponderTests.SuiteMoveResponder.TestSimpleMove||11:08:31 Tue, Jul 07, 2009|
 |FitNesse.SuiteAcceptanceTests.SuiteResponderTests.SuiteMoveResponder.TestReferencesOfChildOfMovedPageAreRenamed||11:08:02 Tue, Jul 07, 2009|
 |FitNesse.SuiteAcceptanceTests.SuiteResponderTests.SuiteMoveResponder.TestMovePageWithSubPages||11:04:14 Tue, Jul 07, 2009|
-|FitNesse.SuiteAcceptanceTests.SuiteResponderTests.SuiteMoveResponder.TestMovePageWithExternalReference||11:03:44 Tue, Jul 07, 2009|
-|FitNesse.SuiteAcceptanceTests.SuiteResponderTests.SuiteMoveResponder||11:03:06 Tue, Jul 07, 2009|
-|FitNesse.SuiteAcceptanceTests.SuiteResponderTests.SuiteMoveResponder.TestMovePageThreeLevelsDown||11:02:37 Tue, Jul 07, 2009|
-|FitNesse.UserGuide.SliM.ScriptTable||09:53:27 Wed, Jun 24, 2009|
-|JunkPage.PointOfSale.ScenarioLibrary||21:17:23 Tue, Jun 23, 2009|
-|JunkPage.PointOfSale||20:45:48 Tue, Jun 23, 2009|