README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# audit.connect

<!-- badges: start -->
[![R-CMD-check](https://github.com/jumpingrivers/audit.connect/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jumpingrivers/audit.connect/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

This checks that a variety of applications can be deployed to a Posit Connect Server.

## Installation

To install the R package, run

```{r, eval = FALSE}
install.packages("audit.connect")
```
For python based deployment, the python package, `rsconnect-python` is required

```{bash, eval = FALSE}
pip install rsconnect-python
```

## Usage

Running the test is straightforward

```{r, eval = FALSE}
library("audit.connect")
check(server = "https://www.connect.server.name/",
      token = "API_TOKEN")
```
Alternatively, you can set environmental variables, `CONNECT_SERVER` and `CONNECT_API_KEY` in your
`.Renviron` file.

## Connect Package Pollution

If you are running this package on a machine you normally use to deploy to Connect, then 
this isn't an issue - you can skip the next part.

**If** you are using a machine where you are deploying to Connect for the
first time, then read one!

Connect package pollution occurs when

 * we use package manager binaries, **and**
 * the OS on Connect differs to the OS on the deployment machine.
 
If you aren't using binaries or the OS is the same, then you won't have any issue. 
If you want to be sure, we can use {renv}

```{r, eval = FALSE}
# Ensure we don't use the existing renv cache
fs::dir_delete(renv::paths$cache())
# Use the slow installation method
renv::init(repo = "https://cloud.r-project.org/")
renv::install("remotes")
```


## Config file

Experimental. You can skip deployment tests, by setting the appropriate value in `config-uat.yml`.
This file can be auto-generated via

```{r, eval = FALSE}
create_config()
```
If a test is missing in the config, the default value is TRUE.

## Creating a test

Tests are R6 classes. To be automatically detected, the class name **must**
start with `check_`. If you copy/paste the following code into `R/example.R`,
when you run `check()`, the test is automatically detected and run.
Likewise, `create_config()`

``` r
#' @export
check_example = R6::R6Class(
  "check_example",
  inherit = uatBase::base_check,
  # A function is passed to checker()
  # This runs the test, detects errors, and logs the result
  public = list(
    #' @description Runs a UAT check
    check = function(account = NULL) {
      private$checker(example_test())
      return(invisible(NULL))
    }
  ),
  # Multiple classes can have the same group.
  # But context/short should be unique
  private = list(
    context = "Human description",
    short = "config_variable",
    group = "config_group"
  )
)

example_test = function() {
  return(TRUE)
}
```