Package 'piktests'

piktests: Run PIK Integration Tests

Description

This package includes integration tests for selected models and packages related to those models.

Author(s)

Maintainer: Pascal Führlich [email protected]

Authors:

• Jan Philipp Dietrich [email protected]

See Also

Useful links:

• https://github.com/pik-piam/piktests

---

baseComputations

Description

A list of computation objects to be used by run via the 'whatToRun' parameter.

Usage

baseComputations

Format

An object of class list of length 7.

Details

Each computation object is a list with a setup and a compute function. These are called at the appropriate times during a piktests run.

Author(s)

Pascal Führlich

---

createRunFolder

Description

Constructs a folder name based on current data and existing folders

Usage

createRunFolder(
  computationNames = c("magpiePrep", "remindPrep"),
  piktestsFolder = getwd(),
  runFolder = NULL
)

Arguments

computationNames	These are appended to the created folder's name.
piktestsFolder	A new folder for this piktests run is created in the given directory.
runFolder	Path where a folder for this piktests run should be created. Generally should be left as default, which creates a folder name based on the current date and computationNames.

Author(s)

Jan Philipp Dietrich

---

run

Description

Runs integration tests in an isolated runtime environment.

Usage

run(
  renvInstallPackages = NULL,
  computations = c("magpiePrep", "remindPrep"),
  piktestsFolder = getwd(),
  runFolder = NULL,
  jobNameSuffix = "",
  executionMode = c("slurm", "directly"),
  localCache = TRUE
)

Arguments

renvInstallPackages	After installing other packages, renv::install(renvInstallPackages) is called. Use this to test changes in your fork by passing "<gituser>/<repo>" (e.g. "pfuehrlich-pik/madrat").
computations	A named list of "computations", or names of computations predefined in baseComputations. A computation consists of a setup and a compute function. See example for a valid computation list.
piktestsFolder	A new folder for this piktests run is created in the given directory.
runFolder	Path where a folder for this piktests run should be created. Generally should be left as default, which creates a folder name based on the current date, time, and the computation names.
jobNameSuffix	A suffix to be appended to the SLURM job's name.
executionMode	Determines how long running jobs are started. One of "slurm", "directly"
localCache	If TRUE (default) use a new and empty cache folder, otherwise 'getConfig("cachefolder")'.

Details

The preconfigured madrat source and mapping folders are used, otherwise a subfolder of the newly created run folder is used as madrat mainfolder.

Value

Invisibly, the path to the folder holding everything related to this piktests run.

Author(s)

Pascal Führlich, Jan Philipp Dietrich

See Also

baseComputations

Examples

## Not run: 
piktests::run(renvInstallPackages = c("tscheypidi/madrat", "[email protected]"),
              computations = list(testComputation = list(setup = function() message("Hello"),
                                                         compute = function() message("World"))),
               executionMode = "directly",
               localCache = FALSE)

## End(Not run)

---

runInRenv

Description

Experimental. Create an renv with all packages needed to run the given function and run that function in that renv.

Usage

runInRenv(
  work,
  ...,
  targetFolder = ".",
  renvLockfile = NULL,
  renvPreInstall = NULL
)

Arguments

work	A function that should be executed in the newly created renv.
...	Arguments passed to runLongJob. 'renvToLoad' will be set automatically.
targetFolder	Where the renv is created.
renvLockfile	Optional. An renv lockfile used to create the renv. If NULL auto-detect dependencies instead.
renvPreInstall	Optional. A function that is run right after initializing the renv, can be used to apply system specific fixes.

---

runLongJob

Description

Run a function in a new R session, per default via SLURM (see executionMode). The log will be written to 'file.path(workingDirectory, "job.log")'.

Usage

runLongJob(
  workFunction,
  arguments = list(),
  workingDirectory = getwd(),
  renvToLoad = NULL,
  madratConfig = NULL,
  jobName = opts_slurmR$get_job_name(),
  executionMode = c("slurm", "directly")
)

Arguments

workFunction	This function will be run in a new R session, so it must use '::' whenever package functions are used. Also it cannot refer to variables in the outer scope, use the next parameter (arguments) to pass them.
arguments	A list of arguments passed to workFunction.
workingDirectory	The working directory in which workFunction will be called.
renvToLoad	The renv project to load before running workFunction.
madratConfig	A madrat config (as returned by 'madrat::getConfig()') to be used when running workFunction.
jobName	The SLURM job's name.
executionMode	Determines how workFunction is started. "slurm" -> 'slurmR::Slurm_lapply', "directly" -> 'callr::r'

Author(s)

Pascal Führlich

---

runWithComparison

Description

Starts two piktests runs, one with default packages and another one with renvInstallPackages installed, so they can be compared. Run this to test changes in your fork by passing "<gituser>/<repo>" (e.g. "pfuehrlich-pik/madrat"). Use the shell scripts created in the run folder to compare logs after all runs are finished.

Usage

runWithComparison(
  renvInstallPackages,
  computations = c("magpiePrep", "remindPrep"),
  piktestsFolder = getwd(),
  diffTool = c("delta", "colordiff", "diff"),
  ...
)

Arguments

renvInstallPackages	Only in the second run, after installing other packages, 'renv::install(renvInstallPackages)' is called.
computations	A named list of "computations", or names of computations predefined in baseComputations. A computation consists of a setup and a compute function. See example for a valid computation list.
piktestsFolder	A new folder is created in the given directory. In that folder two folders called "old" and "new" are created which contain the actual piktests runs.
diffTool	One or more names of command line tools for comparing two text files. The first one that is found via 'Sys.which' is used in the comparison shell script. If none is found falls back to "diff".
...	Additional arguments passed to run.

Value

Invisibly, the path to the folder holding the two actual piktests runs.

Author(s)

Pascal Führlich

See Also

run, baseComputations

---

setupRenv

Description

Sets up a fresh renv and installs the required packages in it.

Usage

setupRenv(targetFolder, renvInstallPackages, computationsSourceCode)

Arguments

targetFolder	Where to setup the renv.
renvInstallPackages	renv::install(renvInstallPackages) is called. Use this to test changes in your fork by passing "<gituser>/<repo>" (e.g. "pfuehrlich-pik/madrat").
computationsSourceCode	A character vector containing the source code to create a list of computations (see baseComputations), usually 'deparse(piktests::computations)'. Passing the computations like this has two reasons: The environments associated with the functions in the computations are stripped. These associated environments are only valid in the R session they originate from, but because setupRenv is run in a separate R session they are invalid here. The other advantage is that setupRenv does not need to install piktests just to get access to the computations.

Details

This function should be called in a fresh R session (e.g. via callr::r), because setting up an renv involves changing critical aspects of your R session like your libpaths.

Author(s)

Pascal Führlich

See Also

baseComputations

Examples

## Not run: 
computations <- piktests::baseComputations[c("madratExample",
                                             "magpiePreprocessing")]
callr::r(piktests:::setupRenv,
         list(targetFolder = tempdir(),
              renvInstallPackages = c("tscheypidi/madrat", "[email protected]"),
              computationsSourceCode = deparse(computations)),
         show = TRUE)

## End(Not run)

---