# A simple project

This chapter shows how to use Ick to test a simple project on one
target. It does this using the [yarn](http://liw.fi/cmdtest/])
scenario testing language.

    SCENARIO build simple project

For running these tests, the caller must set the
`ICK_UNSTABLE_TEST_TARGET` and `ICK_JESSIE_TEST_TARGET` environment
variables to addresses that can be reached by ssh and where `sudo
pbuilder` can be run without interactive password entry.

    GIVEN the ICK_UNSTABLE_TEST_TARGET variable is set
    AND   the ICK_JESSIE_TEST_TARGET variable is set

First of all, we need to have a project we build. We call the project
FOO. For this example, it can be empty, since we don't actually need
to build anything.

    GIVEN a minimal project repository in FOO.git

We also need an ick file that specifies the target machine and the
project. We use `localhost` as the target: we can't assume the
existence of any other machine. Obviously, `localhost` needs to have
been set up correctly; most importantly, the user running Ick must
have ssh access to it, preferably without having to type a key
passphrase or a login password all the time.

    GIVEN an ick file KITTEN.ick containing
    ... {
    ...     "state": "KITTEN.state",
    ...     "targets": {
    ...         "test": {
    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/ci.tgz"
    ...         }
    ...     },
    ...     "projects": {
    ...         "FOO": {
    ...             "git": "FOO.git",
    ...             "branch": "master",
    ...             "pipelines": ["shell"],
    ...             "shell": "echo BUILDING FOO\ntest -d .git\n"
    ...         }
    ...     }
    ... }

The `test` command is there because we want to verify that the source
repository has been cloned.

Note that we use a very silly command to build the project. The only
thing we are showing is that Ick runs the build command, not that
actual building works. If Ick can run one shell command, it can run
any of them, so actual build commands would also work.

Then we run Ick and check that the output contains the output of the
build command.

    WHEN user runs ick KITTEN.ick
    THEN ick build log for FOO in KITTEN.state contains "BUILDING FOO"
    AND there is 1 build log for FOO in KITTEN.state

If we now run Ick again, it shouldn't do anything, since nothing in
the git repository has changed.

    WHEN user runs ick KITTEN.ick
    THEN there is 1 build log for FOO in KITTEN.state

There we go. That's all you should need to know to run builds and
build-time tests for a simple project. This doesn't produce Debian
packages, but for simple cases that's not needed.