.README.md 4.08 KB
Newer Older
1 2
#### integration testing

Valentin Reis's avatar
Valentin Reis committed
3 4
This repository contains integration tests that validate the argo stack,
leveraging the 'argopkgs' repo
5

Valentin Reis's avatar
Valentin Reis committed
6 7
The intended usage is to override (some of) the source(s) with WIP
version(s), as part of development or continuous integration. This
8 9
gitlab CI snippets shows how to do this on a nix-enabled runner. Mind
that this setup tracks argotest master.
10

Valentin Reis's avatar
Valentin Reis committed
11
### Usage (tl;dr, I already have nix on my machine.)
12

Valentin Reis's avatar
Valentin Reis committed
13 14 15
```bash
nix-shell -E '
(import( builtins.fetchGit {
16
  url = https://xgitlab.cels.anl.gov/argo/argotest.git;
Valentin Reis's avatar
Valentin Reis committed
17 18 19 20 21 22
  ref="master";
}) {
  #nrm-src = /path/to/nrm
  #libnrm-src = /path/to/nrm
  #containers-src = /path/to/nrm
  }).test' --run "argotk.hs helloworld"
23 24
```

Valentin Reis's avatar
Valentin Reis committed
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
### 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'
```
45

Valentin Reis's avatar
Valentin Reis committed
46 47 48 49
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. 
50

Valentin Reis's avatar
Valentin Reis committed
51 52 53
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:
54 55 56 57

```nix
nix-shell -E '{ argotest ? (builtins.fetchGit {
    url = https://xgitlab.cels.anl.gov/argo/argotest.git;
Valentin Reis's avatar
Valentin Reis committed
58
    ref="master";})
59 60 61 62 63 64 65 66 67 68 69 70 71 72
}:
(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'
```

Valentin Reis's avatar
Valentin Reis committed
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
- [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
```

Valentin Reis's avatar
Valentin Reis committed
96
#### Misc 
Valentin Reis's avatar
Valentin Reis committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110

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:
111 112 113 114 115 116 117 118 119 120 121 122 123 124

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

- Builds may fail if `PWD` is in a `nosuid`-enabled filesystem.

- 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

For example, we could setup the CI for the `containers` repo like:
``` {.yml}
125 126 127
integration.test:
  stage: test
  script:
128 129 130 131 132 133
    - 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'
134 135
  artifacts:
    paths:
136 137 138 139 140 141
      - 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
142 143 144 145 146 147 148 149
    expire_in: 1 week
  except:
    - /^wip\/.*/
    - /^WIP\/.*/
  tags:
    - integration
```

150
### Hacking
151 152 153

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

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