.README.md 3.8 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

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

11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
### Usage

- Get Nix: `curl https://nixos.org/nix/install | sh`

- Use the 'argotest' nix function to provide an environment, among which the
  `argotk.hs` tool, which runs tests. For example, we can run default tests
  using pinned `argopkgs` sources like so:

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

Alternatively, one can get rid of the `--run` option  in order to be provided
with an environment in which all the argo components should be in the `PATH`,
along with the `argotk.hs` tool.

The arguments to the argotest function are defined in the default.nix file in
this repository. They all have default values.

For a more involved example, let's run a test in a custom environment. Here,
we'll run the 'helloworld' test in an environment that uses a local `nrm`
source, the master `libnrm` branch and a specific revision of the `containers`
Valentin Reis's avatar
Valentin Reis committed
36
branch. We'l'l use the master `argotest` branch for that.
37 38 39 40

```nix
nix-shell -E '{ argotest ? (builtins.fetchGit {
    url = https://xgitlab.cels.anl.gov/argo/argotest.git;
Valentin Reis's avatar
Valentin Reis committed
41
    ref="master";})
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
}:
(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'
```

*WARNING* 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.

- 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:

```nix
nix-shell -E '{ argotest ? /path/to/argotest }:
(import argotest {
  nrm-src = /path/to/nrm;
  # libnrm-src left at default argument value (inherits from argopkgs)
  # containers-src left at default argument value (inherits from argopkgs)
}).test' --run 'argotk.hs helloworld'
```

### Example CI setup

For example, we could setup the CI for the `containers` repo like:
``` {.yml}
80 81 82
integration.test:
  stage: test
  script:
83 84 85 86 87 88
    - 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'
89 90
  artifacts:
    paths:
91 92 93 94 95 96
      - 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
97 98 99 100 101 102 103 104
    expire_in: 1 week
  except:
    - /^wip\/.*/
    - /^WIP\/.*/
  tags:
    - integration
```

105
### Argotk.hs usage:
106

Valentin Reis's avatar
Valentin Reis committed
107 108
Commands list:  

109
```{.bash}
110
argotk.hs --help
111 112 113
```
Output:
```{.txt pipe="sh"}
114
root/argotk/argotk.hs --help
115
```
116

Valentin Reis's avatar
Valentin Reis committed
117 118
Detailed help:  

119
```{.bash}
120
argotk.hs helloworld --help
121
```
Valentin Reis's avatar
Valentin Reis committed
122
Output:
123
```{.txt pipe="sh"}
124
root/argotk/argotk.hs helloworld --help
125 126
```

127
### Hacking
128 129 130

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

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