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

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

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

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

Valentin Reis's avatar
Valentin Reis committed
21 22
### Usage (in three parts)

Valentin Reis's avatar
Valentin Reis committed
23
- [**1**] Get Nix: `curl https://nixos.org/nix/install | sh`
Valentin Reis's avatar
Valentin Reis committed
24

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

Valentin Reis's avatar
Valentin Reis committed
42 43 44 45
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. 
46

Valentin Reis's avatar
Valentin Reis committed
47 48 49
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:
50 51 52 53

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

Valentin Reis's avatar
Valentin Reis committed
69
- [**3**] The `test`environment contains the `argotk.hs` tool, which runs various
Valentin Reis's avatar
Valentin Reis committed
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
operations on the argo stack:

Commands list:  

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

Detailed help:  

```{.bash}
Valentin Reis's avatar
Valentin Reis committed
85
argotk.hs TestHello --help
Valentin Reis's avatar
Valentin Reis committed
86 87 88
```
Output:
```{.txt pipe="sh"}
Valentin Reis's avatar
Valentin Reis committed
89
root/argotk/argotk.hs TestHello --help
Valentin Reis's avatar
Valentin Reis committed
90 91
```

Valentin Reis's avatar
Valentin Reis committed
92
#### Misc 
Valentin Reis's avatar
Valentin Reis committed
93 94 95 96 97 98 99 100

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";
Valentin Reis's avatar
Valentin Reis committed
101
}) {}).test' --run "argotk.hs TestHello"
Valentin Reis's avatar
Valentin Reis committed
102 103 104 105 106
```

#### WARNINGS

There are a few things one has to be aware of using this workflow:
107 108 109 110 111 112

- 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
Valentin Reis's avatar
Valentin Reis committed
113
  sources on the fly.
114 115

### Hacking
116 117 118

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

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