# Introduction

The tick test suite has been designed not only to non-interactively
test tick, but also to aid in the development of test cases and the
interactive execution of tick in a test environment.

The driver program of the test suite is `run-tests.sh`, which takes as
argument a Scheme test file.  `run-tests.sh` will set up a sandbox
environment to execute tick, initializing its database in a "work
directory", and will execute the Scheme file given as argument.

By default, `run-tests.sh` will create the test environment before
executing tests, and will destroy it at the end of its execution
(including deleting the work directory).

# Test cases

Conventionally, tick test cases are written in `test-*.scm` files.
They typically use the API provided by the test egg.

Test files should expect to be executed with an empty ticket database.
If tests require tickets to exist, tests must create them.

For compatibility with `chicken-install -test`, `tests/run.scm` simply
calls `run-tests.sh` over all tick test files.

# Tests execution interface

The Tick test suite respects the following environment variable:

* `TICK_TEST_WORK_DIR`: Path to the directory that will be used as
  work directory for tests.  The directory will be created if it
  doesn't exist.  If this variable is not set, a new directory with an
  arbitrary name will be used.

* `TICK_TEST_KEEP_WORK_DIR`: By default, the test suite will delete
  `TICK_TEST_WORK_DIR` at the end of its execution.  Setting this
  variable prevents that.

* `TICK_TEST_REUSE_WORK_DIR`: By default, `TICK_TEST_WORK_DIR` will be
  freshly populated at the beginning of the execution of the test
  suite.  If this variable is set, and key directories for the test
  suite exist, the test suite will skip setting up
  `TICK_TEST_WORK_DIR`.

* `TICK_TEST_SPAWN_SHELL`: If set, its value is expected to be the
  executable of a shell, which will be spawned with the environment
  set up to run tick after executing tests.  This variable is most
  useful when you want to get a shell on a tick test environment to
  try things out.

* `TICK_TEST_SHELL_ON_ERROR`: If set, its value is expected to be the
  executable of a shell, which will be spawned with the environment
  set up to run tick on errors in the execution of tests.  This
  variable is most useful when multiple tests are executed in sequence
  and you want to get a shell on the first error.

* `TICK_TEST_DEBUG`: When set, will cause both `csi` and
  `run-tests.sh` to print expressions as they are evaluated.

When running a shell on tick test environments, the environment
variables prefixed by `TICK_` can be useful to locate tick files.
Example:

```
$ env | grep TICK
TICK_SERVER_GIT_REPO_DIR=/tmp/tmp.IDqHREJqob/server-git-repo
TICK_SERVER_URL=file:///tmp/tmp.IDqHREJqob/server-git-repo
TICK_CACHE_DIR=/tmp/tmp.IDqHREJqob/
TICK_CONF_DIR=/tmp/tmp.IDqHREJqob/conf
TICK_TEST_WORK_DIR=/tmp/tmp.IDqHREJqob
```

See also the documentation of the
[test egg](https://wiki.call-cc.org/eggref/5/test)
for environment variables supported by it.


# Practical examples

## Run a shell on the tick test environment

```
$ TICK_TEST_SPAWN_SHELL=bash ./run-tests.sh test-null.scm
```

`test-null` is just a dummy file for when you want to get a shell in
the test environment, but don't want to run any test.

You can also use any Scheme file as argument to `run-tests.sh`. For
example, to populate the tick DB with tickets, so that you can
interactively develop tests (you can also run tick itself on the
shell).

For example, you can get a shell to play with tick on the database
created by the `test-create.scm` tests:

```
$ TICK_TEST_SPAWN_SHELL=bash ./run-tests.sh test-create.scm
```

## Drop into a shell on test errors

Typical use case: you want to debug a particular test case of the test
suite by inspecting the test environment (e.g., running tick on the
shell, looking into the database).

```
$ TICK_TEST_SHELL_ON_ERROR=bash csi -s run.scm
```