# future.tests: Test Suite for ‘Future API’ Backends

The **[future](https://future.futureverse.org)** package defines the
Future API which consists of a small number of functions for writing
[R](https://www.r-project.org) 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](https://future.batchtools.futureverse.org)**,
**[future.callr](https://future.callr.futureverse.org)** and
**[future.mirai](https://future.mirai.futureverse.org)**. 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](https://future.futureverse.org/articles/future-6-future-api-backend-specification.html).
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](https://future.tests.futureverse.org)** - provides a
test suite for validation that a future backend complies with the Future
API.

![](articles/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](https://future.tests.futureverse.org)** 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; }
```

## 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.

# Package index

## All functions

- [`add_test_plan()`](https://future.tests.futureverse.org/reference/add_test_plan.md)
  : Add a Future Plan to Test Against
- [`along_test_plans()`](https://future.tests.futureverse.org/reference/along_test_plans.md)
  : Evaluate an Expression Across A Set of Future Plans
- [`check()`](https://future.tests.futureverse.org/reference/check.md) :
  Run All or a Subset of the Tests Across Future Plans
- [`check_plan()`](https://future.tests.futureverse.org/reference/check_plan.md)
  : Run All Tests
- [`evaluate_expr()`](https://future.tests.futureverse.org/reference/evaluate_expr.md)
  : Evaluate an R Expression
- [`load_tests()`](https://future.tests.futureverse.org/reference/load_tests.md)
  : Loads Future Tests
- [`make_test()`](https://future.tests.futureverse.org/reference/make_test.md)
  : Make a Test
- [`register_test()`](https://future.tests.futureverse.org/reference/register_test.md)
  : Register a Test
- [`run_test()`](https://future.tests.futureverse.org/reference/run_test.md)
  : Run a Test
- [`run_tests()`](https://future.tests.futureverse.org/reference/run_tests.md)
  : Run All Tests
- [`skip_test()`](https://future.tests.futureverse.org/reference/skip_test.md)
  : Skip The Current Test
- [`subset_tests()`](https://future.tests.futureverse.org/reference/subset_tests.md)
  : Identify Subset of Tests with Specified Tags and that Support
  Specified Argument Settings

# Articles

### All vignettes

- [future.tests: An
  Introduction](https://future.tests.futureverse.org/articles/future.tests-01-intro.md):
- [future.tests: Continuous Integration on GitHub
  Actions](https://future.tests.futureverse.org/articles/future.tests-05-ci-github_actions.md):
- [future.tests: Continuous Integration on Travis
  CI](https://future.tests.futureverse.org/articles/future.tests-05-ci-travis.md):