This patch does the following:

- Rewrites INSTALL.txt
- Fixes various inaccuracies in README.txt.
- Adds an admin/help/simpletest page that explains how to use the module.
- Adds a handbook page at http://drupal.org/handbook/modules/simpletest with the contents of this page (for consistency with other modules, as well as for easy review :)).
- Changes the titles on the main SimpleTest page to just "SimpleTest", for consistency with other modules.

INSTALL.txt before:

Install
-----------------------

- Copy this module package to your modules directory
- Install the simpletest framework to a new subdirectory of simpletest module: modules/simpletest/simpletest
  You can find it at https://sourceforge.net/project/showfiles.php?group_id=76550
- At least Version 1.0.1 alpha3 of the simpletest framework is required (for upload tests).
- Activate the simpletest.module
- Visit the admin/simpletest page

INSTALL.txt after:

$Id$

Installation
------------
1. Uncompress the SimpleTest module package to your sites/all/modules directory.
2. Download the latest SimpleTest package from SourceForge.net:
   https://sourceforge.net/project/showfiles.php?group_id=76550&package_id=77275
   Note: At least version 1.0.1 alpha3 is required (for upload tests)
3. Uncompress it inside your SimpleTest module directory:
   sites/all/modules/simpletest/simpletest
4. Go to Administer >> Site Building >> Modules (admin/build/modules) and
   enable the SimpleTest module.
5. Go to Administer >> Site building >> SimpleTest (admin/build/simpletest) to
   begin using the module.
6. (Optional) Go to Administer >> Help >> SimpleTest (admin/help/simpletest) fo
   more information on how to use the SimpleTest module.
7. (Optional) Go to Administer >> Site configuration >> SimpleTest
   (admin/settings/simpletest) to configure advanced settings.

admin/help/simpletest:
See http://drupal.org/handbook/modules/simpletest. Please make any edits there directly, and I can get them incorporated into the patch.

Old README.txt:

Description
-----------------------
A framework for running unit tests in Drupal.

USAGE WARNING
-----------------------
NEVER USE THIS MODULE IN A PRODUCTION ENVIRONMENT!
While running a test this module may (completely) change your Drupal setup.
Though it usually recovers the original setup at the end of a test, there is
no guarantee that it will work correctly, especially if an error or timeout
occurs.

Since all registered users have the registered users role this role
MUST have the default settings for current tests to run correct.
This also applies for anonymous user.


Status
-----------------------
Some core tests have been written - see the /tests subdirectory. We need more,
especially for contributed modules.

Simpletest hook
-----------------------
This module offers a new 'simpletest' hook. Modules implementing this hook should return an array of paths which
point to test files. These paths should be relative to the /simpletest directory.

Writing Tests
-----------------------
Please write some tests.
See http://drupal.org/simpletest

Authors
-----------------------
Moshe Weitzman < weitzman at tejasa dot com >
Kuba Zygmunt   < kuba.zygmunt at gmail dot com >
Thomas Ilsche  < ThomasIlsche at gmx dot de >

Thanks
-----------------------
to Google for sponsoring the testsuite Summer of Code project.
see http://code.google.com/summerofcode.html

New README.txt:

$Id$

Description
-----------
A framework for running unit tests in Drupal.

USAGE WARNING
-------------
NEVER USE THIS MODULE IN A PRODUCTION ENVIRONMENT!
While running a test this module may (completely) change your Drupal setup.
Though it usually recovers the original setup at the end of a test, there is
no guarantee that it will work correctly, especially if an error or timeout
occurs.

Status
------
Drupal core tests are in the /tests subdirectory. We need people to help
expand our library of core tests, as well as provide tests for contributed
modules.

Documentation
-------------
* Official SimpleTest documentation:
  http://simpletest.org/en/start-testing.html
* SimpleTest module API documentation:
  http://drupal.org/simpletest
* An Introduction to Unit Testing in Drupal:
  http://www.lullabot.com/articles/introduction-unit-testing
* A Drupal Module Developer's Guide to SimpleTest:
  http://www.lullabot.com/articles/drupal-module-developer-guide-simpletest

Module Authors
--------------
* Moshe Weitzman < weitzman at tejasa dot com >
* Kuba Zygmunt   < kuba.zygmunt at gmail dot com >
* Thomas Ilsche  < ThomasIlsche at gmx dot de >
* Rok Zlender    < rok.zlender at gmail dot com >

Thanks
------
* Google for sponsoring the initial test suite (and subsequent improvements)
  as Summer of Code projects:
  http://code.google.com/soc/
* Google and all students/mentors involved in the creation of a huge set of
  core tests during the Google Highly Open Participation contest:
  http://code.google.com/opensource/ghop/

If you know of any other documentation resources, please let me know so we can get them added! The point of this patch is to make it as simple as possible for someone who wants to figure out what all this SimpleTest stuff is all about to do so quickly.

(note: the weirdness of the thing after the URL being displayed right after the URL is some weird codefilter bug; not in the actual text)

The API docs need a lot of love, but I'll handle that separately. In the meantime, reviews of this would be greatly appreciated!

Comments

webchick’s picture

StatusFileSize
new8.14 KB
keith.smith’s picture

Status: Needs review » Needs work
+   Note: At least version 1.0.1 alpha3 is required (for upload tests)

add period.

+3. Uncompress it inside your SimpleTest module directory:
+   sites/all/modules/simpletest/simpletest

Uncompress it so that it is the directory sites/all/modules/simpletest/simpletest, or becomes a directory under this directory?

+4. Go to Administer >> Site Building >> Modules (admin/build/modules) and
+   enable the SimpleTest module.

lowercase "building"

+6. (Optional) Go to Administer >> Help >> SimpleTest (admin/help/simpletest) fo
+   more information on how to use the SimpleTest module.

fo = for

+      $output .= '<p>'. t('To begin, visit <a href="@admin-simpletest">Administer >> Site building >> SimpleTest</a> to bring up the main screen. Here, you will see a list of available test groups, which may be checked off individually to run a subset whose results you are interested in. You may also choose to run <em>all</em> tests (which will take <strong>several minutes</strong> to finish), if you are interested in more comprehensive results.', array('@admin-simpletest' => url('admin/build/simpletest'))) .'</p>';
+      $output .= '<p>'. t('After the tests have run, a message will be displayed next to each test group indicating whether tests within it passed, failed, or had exceptions. A pass means that intended test results happened as expected. A fail means that they did not. An exception normally indicates an error outside of the test, such as a PHP warning or notice. If there were fails or exceptions, the results are expanded, and the tests that had issues will be indicated in red or pink rows. These results can then be used to make refinements in the code and tests until a 100% success rate is achieved.') .'</p>';
+      $output .= '<p>'. t('Extensive API documentation for developers who wish to write tests for their own modules is available at <a href="@simpletest-api">SimpleTest API Documentation</a> in the Drupal handbook.', array('@simpletest-api' => 'http://drupal.org/simpletest')) .'</p>';

how about:

+      $output .= '<p>'. t('Visit <a href="@admin-simpletest">Administer >> Site building >> SimpleTest</a> to display a list of available tests. For comprehensive testing, select <em>all</em> tests, or individually select tests for more targeted testing. (Note: Selecting <em>all</em> tests may take several minutes to complete.)', array('@admin-simpletest' => url('admin/build/simpletest'))) .'</p>';)
+      $output .= '<p>'. t('After the tests have run, a message will be displayed next to each test group indicating whether tests within it passed, failed, or had exceptions. A pass means that a test returned the expected results, while fail means that it did not. An exception normally indicates an error outside of the test, such as a PHP warning or notice. If there were fails or exceptions, the results are expanded, and the tests that had issues will be indicated in red or pink rows. Use these results to refine your code and tests until all tests return a pass.') .'</p>';
+      $output .= '<p>'. t('For more information on creating and modifying your own tests, see the <a href="@simpletest-api">SimpleTest API Documentation</a> in the Drupal handbook.', array('@simpletest-api' => 'http://drupal.org/simpletest')) .'</p>';
webchick’s picture

Status: Needs work » Needs review
StatusFileSize
new8.01 KB

Oooo! Just the person I hoped would wander across this issue. :D

Fixed all the minor stuff, and replaced the help output with your suggestion.

For

+3. Uncompress it inside your SimpleTest module directory:
+   sites/all/modules/simpletest/simpletest

I changed it to:

3. Uncompress it inside your SimpleTest module directory, so the official
   SimpleTest files are located at:
   sites/all/modules/simpletest/simpletest

Is that more clear?

keith.smith’s picture

Assigned: Unassigned » webchick
Status: Needs review » Needs work

That is indeed more clear.

This looks good to me, with the exception of the first paragraph of hook_help, which has two spaces between the first two sentences, rather than one. But that's it, as far as I see! :)

webchick’s picture

Status: Needs work » Needs review
StatusFileSize
new8.01 KB

Brutal. Unrelenting. I love it! :D

One more time?

keith.smith’s picture

Assigned: webchick » Unassigned
Status: Needs review » Reviewed & tested by the community

Hey, I learned from watching the best.

This looks good to me, and is a major improvement. I love that you wrote a help page for this -- I wish more modules did that (now that 6 is in string freeze maybe we could just go on a spree adding help pages to all of contrib).

I didn't really mean to assign this issue to you in #4 -- being able to "Assign" to people other than yourself must be a recent (and cool) change -- so I'm going to "Unassign" it.

webchick’s picture

Assigned: Unassigned » webchick

Oops. Right. That was me being sneaky and trying to assign the issue to myself without actually posting a follow-up, by editing the node directly. The next time a comment was posted, it picked up the change and so it made it look like you changed the assigned-to. So now I'm re-assigning it to myself and will stop doing that from now on to avoid confusion. :D

And heck yes! Anytime you want to add handbook pages for contributed modules, go for it! The http://drupal.org/handbook/config/contribmodules has seen a lot of love recently.

Rok Žlender’s picture

Amazing. The only thing I have to add is we currently need simpletest lib version at least 1.0.1beta2. I changed this and made some coder suggested fixes and committed to HEAD and D5.

Rok Žlender’s picture

Status: Reviewed & tested by the community » Fixed
Anonymous’s picture

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.