Prepare a directory for orderly to use — orderly_test

For interactive testing of orderly code. This runs through and sets everything up as orderly would (creates a new working directory and copies files into it, pulls data from the database, copies over any dependent reports) but then rather than running the report hands back to the user.

Usage

orderly_test_start(
  name,
  parameters = NULL,
  envir = parent.frame(),
  root = NULL,
  locate = TRUE,
  instance = NULL,
  use_draft = FALSE,
  remote = NULL
)

orderly_test_check(path = NULL)

Arguments

name: Name of the report to run (see orderly_list()). A leading src/ will be removed if provided, allowing easier use of autocomplete.
parameters: Parameters passed to the report. A named list of parameters declared in the orderly.yml. Each parameter must be a scalar character, numeric, integer or logical.
envir: The parent of the environment that will be used to evaluate the report script; by default a new environment will be made with the global environment as the parent.
root: The path to an orderly root directory, or NULL (the default) to search for one from the current working directory if locate is TRUE.
locate: Logical, indicating if the configuration should be searched for. If TRUE and config is not given, then orderly looks in the working directory and up through its parents until it finds an orderly_config.yml file.
instance: Select instance of the source database to be used, where multiple instances are configured. Use a single unnamed character string to indicate an instance to match. If given, then this name must be present in all databases where instances are listed in orderly_config.yml, and will be ignored by all database where instances are not given. See the "orderly" vignette for further information.
use_draft: Should draft reports be used for dependencies? This should be used only in development. Valid values are logical (TRUE, FALSE) or use the string newer to use draft reports where they are newer than archive reports. For consistency, always and never are equivalent to TRUE and FALSE, respectively.
remote: Remote to use to resolve dependencies. Use this in order to run a report with the same dependencies as are available on a remote server, particularly when using id = "latest". Note that this is not the same as running orderly_pull_dependencies(), then orderly_run with remote = NULL, as the pull/run approach will use the latest report in your archive but the remote = "remote" approach will use the latest approach in the remote archive (which might be less recent).
path: Path to the report that is currently being run

Value

The path to the report directory

Details

Previous versions of orderly changed into the created directory when using orderly::orderly_test_start, which allowed interactive testing of a report, including ensuring that it has created all expected outputs. However, CRAN rules do not allow changing the working directory, which significantly reduces the usefulness of this function - as such we may remove it entirely in a future version of orderly if it does not prove useful in this more limited form.

The new suggested workflow is:

run orderly_test_start(...) to prepare a report directory
manually change into that directory following the printed instructions
use orderly_test_check to check that your report has created the expected artefacts
manually change back to your original directory

Examples


path <- orderly::orderly_example("minimal")
p <- orderly::orderly_test_start("example", root = path)
#> [ name       ]  example
#> [ id         ]  20230621-105040-76fc2400
#> [ start      ]  2023-06-21 10:50:40
#> [ data       ]  source => dat: 20 x 2
#> orderly has prepared your files at the path
#> 
#>   /tmp/RtmpGRuIRx/file4734aea9c/draft/example/20230621-105040-76fc2400
#> 
#> but unfortunately due to CRAN policies we cannot change the
#> directory to that path.  In order to continue testing your
#> report interactively, please run
#> 
#>     setwd("/tmp/RtmpGRuIRx/file4734aea9c/draft/example/20230621-105040-76fc2400")
#> 
#> you will be responsible for getting back to your previous working
#> directory after this, which you can do with
#> 
#>     setwd("/orderly/docs/reference")
#> 
#> Please see the documentation ?orderly::orderly_test_start for
#> more details

# The data in the orderly example is now available to use
dat
#>                            name     number
#> 1              careful_bobolink 0.40683019
#> 2            uncalorific_bonobo 0.91287592
#> 3                marginal_eagle 0.29360337
#> 4       unterrestrial_slothbear 0.45906573
#> 5              illfated_anchovy 0.33239467
#> 6                    wet_shrimp 0.65087047
#> 7          classless_drafthorse 0.25801678
#> 8            upstanding_tattler 0.47854525
#> 9                 cranky_earwig 0.76631067
#> 10 uninspirable_indianglassfish 0.08424691
#> 11             changeable_bream 0.87532133
#> 12        zealous_emperorshrimp 0.33907294
#> 13            brilliant_nandine 0.83944035
#> 14               waiting_agouti 0.34668349
#> 15           tricolour_xrayfish 0.33377493
#> 16  preagricultural_dromaeosaur 0.47635125
#> 17          rhombohedral_canary 0.89219834
#> 18            necessary_barnowl 0.86433947
#> 19          ethnological_oyster 0.38998954
#> 20       snobbish_capeghostfrog 0.77732070

# Check to see which artefacts have been created so far:
orderly::orderly_test_check(p)
#> [ artefact   ]  mygraph.png: <missing>

# Manually the code that this report has in its script
png(file.path(p, "mygraph.png"))
barplot(setNames(dat$number, dat$name), las = 2)
dev.off()
#> agg_png 
#>       2 

# We now confirm that the artefact has been created:
orderly::orderly_test_check(p)
#> [ artefact   ]  mygraph.png: c486fa4c241c456c72a17f74189a4431