

<div id="badges"><!-- pkgdown markup -->
<a href="https://CRAN.R-project.org/web/checks/check_results_future.tests.html"><img border="0" src="https://www.r-pkg.org/badges/version/future.tests" alt="CRAN check status"/></a> <a href="https://github.com/futureverse/future.tests/actions?query=workflow%3AR-CMD-check"><img border="0" src="https://github.com/futureverse/future.tests/actions/workflows/R-CMD-check.yaml/badge.svg?branch=develop" alt="R CMD check status"/></a>     <a href="https://app.codecov.io/gh/futureverse/future.tests"><img border="0" src="https://codecov.io/gh/futureverse/future.tests/branch/develop/graph/badge.svg" alt="Coverage Status"/></a> <a href="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.yaml"><img src="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.yaml/badge.svg" alt="future compliance" border="0"/></a>
<a href="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.batchtools.yaml"><img src="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.batchtools.yaml/badge.svg" alt="future.batchtools compliance" border="0"/></a>
<a href="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.callr.yaml"><img src="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.callr.yaml/badge.svg" alt="future.callr compliance" border="0"/></a>
<a href="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.mirai.yaml"><img src="https://github.com/futureverse/future.tests/actions/workflows/future_tests-future.mirai.yaml/badge.svg" alt="future.mirai compliance" border="0"/></a>
<a href="https://r-consortium.org/all-projects/funded-projects.html"><img border="0" src="man/figures/R_Consortium-logo-horizontal-white-purple-badge.svg" alt="R Consortium: ISC Project 2017-2"/></a>
</div>

# future.tests: Test Suite for 'Future API' Backends 

The **[future]** package defines the Future API which consists of a small number of functions for writing [R] code that can be evaluated either sequentially or in parallel based on a single setting without having to change anything in the code.  Parallelization can be done via one of many backends, e.g. via built-in multicore, multisession and cluster backends (based on the **parallel** package) or via third-party backends such as **[future.batchtools]**, **[future.callr]** and **[future.mirai]**. The design motto of the Future API is:

> Write once, run anywhere

In order for such code to work regardless of which future backend the end-user chooses, it is critical that the backend fully complies with the [Future API Backend Specification].  A future backend with a 100% compliance rate guarantees that the code will work equally well there as in sequential mode.

This R package - **[future.tests]** - provides a test suite for validation that a future backend complies with the Future API.

![](vignettes/imgs/screencast.gif)


## Validate a Future Backend

All future backends implementing the Future API should validate that they conform to the Future API.  This can be done using the **[future.tests]** package, which provides two APIs for running the tests.  The tests can be performed either from within R or from outside of R from the command line making it easy to include them in package tests and in Continuous Integration (CI) pipelines.

### From Within R

```r
> results <- future.tests::check(plan = "multisession")
> exit_code <- attr(results, "exit_code")
> if (exit_code != 0) stop("One or more tests failed")
```

### From Outside R

```sh
$ Rscript -e future.tests::check --test-plan="multisession"
$ exit_code=$?
$ [[ exit_code -eq 0 ]] || { >&2 echo "One or more tests failed"; exit 1; }
```


[R]: https://www.r-project.org
[future]: https://future.futureverse.org
[future.batchtools]: https://future.batchtools.futureverse.org
[future.callr]: https://future.callr.futureverse.org
[future.mirai]: https://future.mirai.futureverse.org
[future.tests]: https://future.tests.futureverse.org
[Future API Backend Specification]: https://future.futureverse.org/articles/future-6-future-api-backend-specification.html

## Installation
R package future.tests is available on [CRAN](https://cran.r-project.org/package=future.tests) and can be installed in R as:
```r
install.packages("future.tests")
```


### Pre-release version

To install the pre-release version that is available in Git branch `develop` on GitHub, use:
```r
remotes::install_github("futureverse/future.tests", ref="develop")
```
This will install the package from source.  

<!-- pkgdown-drop-below -->

