.\" Man page generated from reStructuredText. . .TH "CH-TEST" "1" "2020-12-20 14:44 Coordinated Universal Time" "0.21" "Charliecloud" .SH NAME ch-test \- Run some or all of the Charliecloud test suite . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ ch\-test [PHASE] [\-\-scope SCOPE] [ARGS] .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp Charliecloud comes with a comprehensive test suite that exercises the container workflow itself as well as a few example applications. \fBch\-test\fP coordinates running the test suite. .sp While the CLI has lots of options, the defaults are reasonable, and bare \fBch\-test\fP will give useful results in a few minutes on single\-node, internet\-connected systems with a few GB available in \fB/var/tmp\fP\&. .sp The test suite requires a few GB (standard scope) or tens of GB (full scope) of storage for test fixtures: .INDENT 0.0 .IP \(bu 2 \fIBuilder storage\fP (e.g., layer cache). This goes wherever the builder puts it. .IP \(bu 2 \fIPacked images directory\fP: image tarballs or SquashFS files. .IP \(bu 2 \fIUnpacked images directory\fP\&. Images are unpacked into and then run from here. .IP \(bu 2 \fIFilesystem permissions\fP directories. These are used to test that the kernel is enforcing permissions correctly. Note that this exercises the kernel, not Charliecloud, and can be omitted from routine Charliecloud testing. .UNINDENT .sp The first three are created when needed if they don’t exist, while the filesystem permissions fixtures must be created manually, in order to accommodate configurations where sudo is not available via the same login path used for running tests. .sp The packed and unpacked image directories specified for testing are volatile. The contents of these directories are deleted before the build and run phases, respectively. .sp In all four cases, when creating directories, only the final path component is created. Parent directories must already exist, i.e., \fBch\-test\fP uses the behavior of \fBmkdir\fP rather than \fBmkdir \-p\fP\&. .sp Some of the tests exercise parallel functionality. If \fBch\-test\fP is run on a single node, multiple cores will be used; if in a Slurm allocation, multiple nodes too. .sp The subset of tests to run mostly splits along two key dimensions. The \fIphase\fP is which parts of the workflow to run. Different parts of the workflow can be tested on different systems by copying the necessary artifacts between them, e.g. by building images on one system and running them on another. The \fIscope\fP allows trading off thoroughness versus time. .sp \fBPHASE\fP must be one of the following: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBbuild\fP Image building and associated functionality, with the selected builder. .TP .B \fBrun\fP Running containers and associated functionality. This requires a packed images directory produced by a successful \fBbuild\fP phase, which can be copied from the build system if it’s not also the run system. .TP .B \fBexamples\fP Example applications. Requires an unpacked images directory produced by a successful \fBrun\fP phase. .TP .B \fBall\fP Execute phases \fBbuild\fP, \fBrun\fP, and \fBexamples\fP, in that order. .TP .B \fBmk\-perm\-dirs\fP Create the filesystem permissions directories. Requires \fB\-\-perm\-dirs\fP\&. .TP .B \fBclean\fP Delete automatically\-generated test files, and packed and unpacked image directories. .TP .B \fBrm\-perm\-dirs\fP Remove the filesystem permissions directories. Requires \fB\-\-perm\-dirs\fP\&. .TP .B \fB\-f\fP, \fB\-\-file FILE\fP Run the tests in the given file only, which can be an arbitrary \fB\&.bats\fP file, except for \fBtest.bats\fP under \fBexamples\fP, where you must specify the corresponding Dockerfile or \fBBuild\fP file instead. This is somewhat brittle and typically used for development or debugging. For example, it does not check whether the pre\-requisites of whatever is in the file are satisfied. Often running \fBbuild\fP and \fBrun\fP first is sufficient, but this varies. .UNINDENT .UNINDENT .UNINDENT .sp Scope is specified with: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB\-s\fP, \fB\-\-scope SCOPE\fP \fBSCOPE\fP must be one of the following; the default is \fBstandard\fP\&. .INDENT 7.0 .IP \(bu 2 \fBquick\fP: Most important subset of workflow. Handy for development. Completion time: 1–2 minutes. .IP \(bu 2 \fBstandard\fP: All tested workflow functionality and a selection of more important examples. Completion time: 5–10 minutes. .IP \(bu 2 \fBfull\fP: All available tests, including all examples. Completion time, hot cache: 7–15 minutes; cold cache: 1–2 hours. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Additional arguments: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB\-b\fP, \fB\-\-builder BUILDER\fP Image builder to use. See ch\-build(1) for how the default is selected. .TP .B \fB\-\-dry\-run\fP Print summary of what would be tested and then exit. .TP .B \fB\-h\fP, \fB\-\-help\fP Print usage and then exit. .TP .B \fB\-\-img\-dir DIR\fP Set unpacked images directory to \fBDIR\fP\&. In a multi\-node allocation, this directory may not be shared between nodes. Default: \fB$CH_TEST_IMGDIR\fP if set; otherwise \fB/var/tmp/img\fP\&. .TP .B \fB\-\-pack\-dir DIR\fP Set packed images directory to \fBDIR\fP\&. Default: \fB$CH_TEST_TARDIR\fP if set; otherwise \fB/var/tmp/pack\fP\&. .TP .B \fB\-\-pedantic (yes|no)\fP Some tests require configurations that are very specific (e.g., being a member of at least two groups) or unusual (e.g., sudo to a non\-root group). If \fByes\fP, then fail if the requirement is not met; if \fBno\fP, then skip. The default is \fByes\fP for CI environments or people listed in \fBREADME.md\fP, \fBno\fP otherwise. .sp If \fByes\fP and sudo seems to be available, implies \fB\-\-sudo\fP\&. .TP .B \fB\-\-perm\-dir DIR\fP Add \fBDIR\fP to filesystem permission fixture directories; can be specified multiple times. We recommend one such directory per mounted filesystem type whose kernel module you do not trust; e.g., you probably don’t need to test your \fBtmpfs\fPes, but out\-of\-tree filesystems very likely need this. .sp Implies \fB\-\-sudo\fP\&. Default: \fBCH_TEST_PERMDIRS\fP if set; otherwise skip the filesystem permissions tests. .TP .B \fB\-\-pack\-fmt FMT\fP Use packed image format \fBFMT\fP (\fBsquash\fP or \fBtar\fP). .TP .B \fB\-\-sudo\fP Enable things that require sudo, such as certain privilege escalation tests and creating/removing the filesystem permissions fixtures. Requires generic \fBsudo\fP capabilities. Note that the Docker builder uses \fBsudo docker\fP even without this option. .TP .B \fB\-\-lustre DIR\fP Use \fBDIR\fP for run\-phase Lustre tests. Default: \fBCH_TEST_LUSTREDIR\fP if set; otherwise skip them. .sp The tests will create, populate, and delete a new subdirectory under \fBDIR\fP, leaving everything else in \fBDIR\fP untouched. .UNINDENT .UNINDENT .UNINDENT .SH EXIT STATUS .sp Zero if all tests passed; non\-zero if any failed. For setup and teardown phases, zero if everything was created or deleted correctly, non\-zero otherwise. .SH BUGS .sp Bats will wait until all descendant processes finish before exiting, so if you get into a failure mode where a test sequence doesn’t clean up all its processes, \fBch\-test\fP will hang. .SH EXAMPLES .sp Many systems can simply use the defaults. To run the \fBbuild\fP, \fBrun\fP, and \fBexamples\fP phases on a single system, without the filesystem permissions tests: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ ch\-test ch\-test version 0.12 ch\-run: 0.12 /usr/local/bin/ch\-run bats: 0.4.0 /usr/bin/bats tests: /usr/local/libexec/charliecloud/test phase: build run examples scope: standard (default) builder: docker (default) use generic sudo: no (default) unpacked images dir: /var/tmp/img (default) packed images dir: /var/tmp/tar (default) fs permissions dirs: skip (default) checking namespaces ... ok checking builder ... found: /usr/bin/docker 19.03.2 bats build.bats build_auto.bats build_post.bats ✓ documentation seems sane ✓ version number seems sane [...] All tests passed. .ft P .fi .UNINDENT .UNINDENT .sp The next example is for a more complex setup like you might find in HPC centers: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Non\-default fixture directories. .IP \(bu 2 Non\-default scope. .IP \(bu 2 Different build and run systems. .IP \(bu 2 Run the filesystem permissions tests. .UNINDENT .UNINDENT .UNINDENT .sp Output has been omitted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C (mybox)$ ssh hpc\-admin (hpc\-admin)$ ch\-test mk\-perm\-dirs \-\-perm\-dir /scratch/$USER/perms \e \-\-perm\-dir /home/$USER/perms (hpc\-admin)$ exit (mybox)$ ch\-test build \-\-scope full (mybox)$ scp \-r /var/tmp/pack hpc:/scratch/$USER/pack (mybox)$ ssh hpc (hpc)$ salloc \-N2 (cn001)$ export CH_TEST_TARDIR=/scratch/$USER/pack (cn001)$ export CH_TEST_IMGDIR=/local/tmp (cn001)$ export CH_TEST_PERMDIRS="/scratch/$USER/perms /home/$USER/perms" (cn001)$ export CH_TEST_SCOPE=full (cn001)$ ch\-test run (cn001)$ ch\-test examples .ft P .fi .UNINDENT .UNINDENT .SH REPORTING BUGS .sp If Charliecloud was obtained from your Linux distribution, use your distribution’s bug reporting procedures. .sp Otherwise, report bugs to: <\fI\%https://github.com/hpc/charliecloud/issues\fP> .SH SEE ALSO .sp charliecloud(7) .sp Full documentation at: <\fI\%https://hpc.github.io/charliecloud\fP> .SH COPYRIGHT 2014–2020, Triad National Security, LLC .\" Generated by docutils manpage writer. .