[commit: packages/Cabal] ghc-head: Describe concerns for PackageTests authors. (32d580d)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/Cabal

On branch  : ghc-head
Link       : http://git.haskell.org/?p=packages/Cabal.git;a=commit;h=32d580d8ddff8623865598bc70e125991e814d05

>---------------------------------------------------------------

commit 32d580d8ddff8623865598bc70e125991e814d05
Author: Thomas Tuegel <ttuegel at gmail.com>
Date:   Mon Apr 29 10:55:41 2013 -0500

    Describe concerns for PackageTests authors.


>---------------------------------------------------------------

32d580d8ddff8623865598bc70e125991e814d05
 Cabal/tests/README |   22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Cabal/tests/README b/Cabal/tests/README
new file mode 100644
index 0000000..5b44814
--- /dev/null
+++ b/Cabal/tests/README
@@ -0,0 +1,22 @@
+Writing Package Tests
+=====================
+
+The tests under the `PackageTests` directory define and build packages which
+exercise various components of Cabal. Each test case is an `HUnit` test. The
+entry point for the test suite, where all the test cases are listed, is
+`PackageTests.hs`. There are utilites for calling the stages of Cabal's build
+process in `PackageTests/PackageTester.hs`; have a look at an existing test case
+to see how they're used.
+
+It is very important that package tests use the in-place version of Cabal,
+rather than the system version. Several long-standing bugs in the test suite
+were caused by testing the system (rather than the newly-compiled) version of
+Cabal. There are two places where the system Cabal can accidentally be invoked:
+1. Compiling `Setup.hs`. `runghc` needs to be told about the in-place package
+database. This issue should be solved for all future package tests; see
+`compileSetup` in `PackageTests/PackageTester.hs`.
+2. Compiling a package which depends on Cabal. In particular, packages with
+`detailed` type test suites depend on the Cabal library directly, so it is
+important that they are configured to use the in-place package database. The
+test suite already creates a stub `PackageSpec` for this case; see
+`PackageTests/BuildTestSuiteDetailedV09/Check.hs` to see how it is used.