cabal-install/tests/README.md

   1 Integration Tests
   2 =================
   3
   4 Each test is a shell script.  Tests that share files (e.g., `.cabal` files) are
   5 grouped under a common sub-directory of [IntegrationTests].  The framework
   6 copies the whole group's directory before running each test, which allows tests
   7 to reuse files, yet run independently.  A group's tests are further divided into
   8 `should_run` and `should_fail` directories, based on the expected exit status.
   9 For example, the test
  10 `IntegrationTests/exec/should_fail/exit_with_failure_without_args.sh` has access
  11 to all files under `exec` and is expected to fail.
  12
  13 Tests can specify their expected output.  For a test named `x.sh`, `x.out`
  14 specifies `stdout` and `x.err` specifies `stderr`.  Both files are optional.
  15 The framework expects an exact match between lines in the file and output,
  16 except for lines beginning with "RE:", which are interpreted as regular
  17 expressions.
  18
  19 [IntegrationTests.hs] defines several environment variables:
  20
  21 * `CABAL` - The path to the executable being tested.
  22 * `GHC_PKG` - The path to ghc-pkg.
  23 * `CABAL_ARGS` - A common set of arguments for running cabal.
  24 * `CABAL_ARGS_NO_CONFIG_FILE` - `CABAL_ARGS` without `--config-file`.
  25
  26 [IntegrationTests]: IntegrationTests
  27 [IntegrationTests.hs]: IntegrationTests.hs