.README.md

#### integration testing

Integration tests that validate the argo stack, leveraging the 'argopkgs'
repository. The intended usage is to override (some of) the source(s) with WIP
version(s), as part of development or continuous integration.

### Usage (tl;dr, I already have nix on my machine.)

```bash
nix-shell -E '
(import( builtins.fetchGit {
  url = https://xgitlab.cels.anl.gov/argo/argotest.git;
  ref="master";
}) {
  #nrm-src = /path/to/nrm
  #libnrm-src = /path/to/nrm
  #containers-src = /path/to/nrm
  }).test' --run "argotk.hs helloworld"
```

### Usage (in three parts)

- [**1**] Get Nix: `curl https://nixos.org/nix/install | sh`

- [**2**] Use the `test` attribute of the argotest' nix attribute set to enter a
  test environment. For example, we can run default tests on the
  "argopkgs-pinned" version of argo components using:

```bash
nix-shell -E '
let
  argotest-src =
    builtins.fetchGit {
      url = https://xgitlab.cels.anl.gov/argo/argotest.git;
      ref="master";
    };
  argotest = import argotest-src {};
in
  argotest.test'
```

This environment has all the necessary Argo components in its PATH. The
argotest function has various arguments, defined in the default.nix file at the
rooto of this repository. They all have default values. For a more involved
example, let's get a custom test environment. 

Here, we'll use an environment that uses a local `nrm` source, the master
`libnrm` branch and a specific revision of the `containers` branch. We'l'l use
the master `argotest` branch for that:

```nix
nix-shell -E '{ argotest ? (builtins.fetchGit {
    url = https://xgitlab.cels.anl.gov/argo/argotest.git;
    ref="master";})
}:
(import argotest {
  nrm-src = /path/to/nrm;
  libnrm-src = builtins.fetchGit {
    url = https://xgitlab.cels.anl.gov/argo/libnrm.git;
    ref="master"; };
  containers-src = builtins.fetchGit  {
    url = https://xgitlab.cels.anl.gov/argo/containers.git;
    ref="fancy-branch-name"; 
    rev="commit-revisions-string";
    };
}).test' --run 'argotk.hs helloworld'
```

- [**3**] The `test`environment contains the `argotk.hs` tool, which runs various
operations on the argo stack:

Commands list:  

```{.bash}
argotk.hs --help
```
Output:
```{.txt pipe="sh"}
root/argotk/argotk.hs --help
```

Detailed help:  

```{.bash}
argotk.hs helloworld --help
```
Output:
```{.txt pipe="sh"}
root/argotk/argotk.hs helloworld --help
```

#### Misc 

Alternatively, one can use the `--run` option to run a test directly:

```bash
nix-shell -E '
(import( builtins.fetchGit {
  url = https://xgitlab.cels.anl.gov/argo/argotest.git;
  ref="master";
}) {}).test' --run "argotk.hs helloworld"
```

#### WARNINGS

There are a few things one has to be aware of using this workflow:

- Builds may fail if the local source repositories are dirty with old build files.

- Without using the `rev` argument, the `builtins.fetchGit` nix command
  prefetches and buffers its output, with an expiration time that ranges ten
  minutes by default. Use a local checkout if you need to modify some of these
  sources on the fly.

### Example CI setup

``` {.yml}
integration.test:
  stage: test
  script:
    - nix-shell -E '{ argotest ? (builtins.fetchGit {
          url = https://xgitlab.cels.anl.gov/argo/argotest.git;
          ref="master";})
      }:
      (import argotest { containers-src = ./. ; }).test' \
      --run 'argotk.hs helloworld'
  artifacts:
    paths:
      - argotest/_output/cmd_err.log
      - argotest/_output/cmd_out.log
      - argotest/_output/daemon_out.log
      - argotest/_output/daemon_out.log
      - argotest/_output/nrm.log
      - argotest/_output/time.log
    expire_in: 1 week
  except:
    - /^wip\/.*/
    - /^WIP\/.*/
  tags:
    - integration
```

### Hacking

- edit `.README.md` in place of README.md.

- the ./shake.hs build file takes care of a few things for the development
  workflow (readme and completion generation).