.README.md 3.86 KB
Newer Older
1 2 3 4 5 6 7
#### integration testing

This repository contains integration tests that validate the argo stack.

It leverages the argopkgs repo, but overrides some sources in it with
their master branch counterparts. see file `default.nix` for details.

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

13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
### 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
38
branch. We'l'l use the master `argotest` branch for that.
39 40 41 42

```nix
nix-shell -E '{ argotest ? (builtins.fetchGit {
    url = https://xgitlab.cels.anl.gov/argo/argotest.git;
Valentin Reis's avatar
Valentin Reis committed
43
    ref="master";})
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 80 81
}:
(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}
82 83 84
integration.test:
  stage: test
  script:
85 86 87 88 89 90
    - 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'
91 92
  artifacts:
    paths:
93 94 95 96 97 98
      - 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
99 100 101 102 103 104 105 106
    expire_in: 1 week
  except:
    - /^wip\/.*/
    - /^WIP\/.*/
  tags:
    - integration
```

107
### Argotk.hs usage:
108 109

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

```{.bash}
118
argotk.hs helloworld --help
119 120
```
```{.txt pipe="sh"}
121
root/argotk/argotk.hs helloworld --help
122 123
```

124
### Hacking
125 126 127

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

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