Commit f0b1f315 authored by Ian D. Bollinger's avatar Ian D. Bollinger
Browse files

README: Reformat tests/README

* Reformat tests/README, add links to individual files.
* Add link to tests/README to HACKING.
* Add links to license files.
parent 3a1a1c19
Writing Package Tests
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 utilities 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.
The tests under the [PackageTests] directory define and build packages
that 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 utilities 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 are 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.
It is 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.
[HUnit]: http://hackage.haskell.org/package/HUnit
......@@ -14,6 +14,8 @@ If you want to hack on Cabal, don't be intimidated!
* There are other resources listed on the [development
wiki](https://github.com/haskell/cabal/wiki).
* See [Cabal/tests/README.md] for information about writing package tests.
Of particular value are the open issues list and the cabal-devel mailing
list, which is a good place to ask questions.
......
......@@ -2,8 +2,8 @@
This Cabal Git repository contains the following packages:
* [Cabal](Cabal/README.md): the Cabal library package
* [cabal-install](cabal-install/README.md): the package containing the `cabal` tool
* [Cabal](Cabal/README.md): the Cabal library package ((license)[Cabal/LICENSE])
* [cabal-install](cabal-install/README.md): the package containing the `cabal` tool ((license)[cabal-install/LICENSE])
See [HACKING.md](HACKING.md) for information about contributing.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment