Run.jl

RunModule

Run

Stable Dev Build Status Codecov Coveralls GitHub last commit

Run.jl provides functions to run tests or build documentation in an isolated environment. See more in the documentation.

Features

  • Simpler CI setup (.travis.yml, .gitlab-ci.yml, etc.)
  • Isolated and activatable sub-environments for Julia < 1.2.
  • Reproducible runs not only for test but also for any sub-projects (docs, benchmarks, etc.)
  • Finer Julia options (e.g., Run.test(fast=true) to run tests faster by minimizing JIT compilation.)

Examples

.github/workflow/*.yml

Here is an example for using Run.jl with GitHub Actions. Create a file, e.g., .github/workflow/test.yml, with:

name: Run tests

on:
  push:
    branches:
      - master
    tags: '*'
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        julia-version: ['1']
      fail-fast: false
    name: Test Julia ${{ matrix.julia-version }}
    steps:
      - uses: actions/checkout@v2
      - name: Setup julia
        uses: julia-actions/setup-julia@v1
        with:
          version: ${{ matrix.julia-version }}
      - run: julia -e 'using Pkg; pkg"add Run@0.1"'
      - run: julia -e 'using Run; Run.prepare_test()'
      - run: julia -e 'using Run; Run.test()'
      - uses: julia-actions/julia-processcoverage@v1
      - uses: codecov/codecov-action@v1
        with:
          file: ./lcov.info
          flags: unittests
          name: codecov-umbrella

.travis.yml

To use Run.test to run tests in Travis CI, add the following snippet in .travis.yml.

before_install:
  - unset JULIA_PROJECT
  - julia -e 'using Pkg; pkg"add Run@0.1"'
install:
  - julia -e 'using Run; Run.prepare_test()'
script:
  - julia -e 'using Run; Run.test()'
after_success:
  - julia -e 'using Run; Run.after_success_test()'
jobs:
  include:
    - stage: Documentation
      install:
        - julia -e 'using Run; Run.prepare_docs()'
      script:
        - julia -e 'using Run; Run.docs()'
      after_success: skip

Side notes:

  • Run.prepare_test() and Run.prepare_docs() are not required but it is a good idea to separate installation and test.
  • The test log can be minimized by passing prepare=false to Run.test.

.gitlab-ci.yml

.template:
  image: julia
  before_script:
    - julia -e 'using Pkg; pkg"add Run@0.1"'

test:
  extends: .template
  script:
    - julia -e 'using Run; Run.test()'

pages:
  extends: .template
  stage: deploy
  script:
    - julia -e 'using Run; Run.docs()'
    - mv docs/build public
  artifacts:
    paths:
      - public
  only:
    - master
source
Run.scriptFunction
Run.script(path; <keyword arguments>)

Run Julia script at path after activating $path/Project.toml.

See also Run.test and Run.docs.

Keyword Arguments

  • project::String: Project to be used instead of $path/../Project.toml.
  • parentproject::String: Project to be added to project if it does not have corresponding manifest file.
  • fast::Bool = false: Try to run it faster (more precisely, skip prepare and pass --compile=min option to Julia subprocess.)
  • prepare::Bool = !fast: Call Run.prepare_test if true (default).
  • compiled_modules::Union{Bool, Nothing} = nothing: Use --compiled-modules=yes (--compiled-modules=no) option if true (false). If false, it also skips precompilation in the preparation phase.
  • precompile::Bool = (compiled_modules != false): Precompile project before running script.
  • strict::Bool = true: Do not include the default environment in the load path (more precisely, set the environment variable JULIA_LOAD_PATH=@).
  • code_coverage::Bool = false: Control --code-coverage option.
  • check_bounds::Union{Nothing, Bool} = nothing: Control --check-bounds option. nothing means to inherit the option specified for the current Julia session.
  • depwarn::Union{Nothing, Bool, Symbol} = nothing: Use --depwarn setting of the current process if nothing (default). Set --depwarn=yes if true or --depwarn=no if false. A symbol value is passed as --depwarn value. So, passing :error sets --depwarn=error.
  • xfail::bool = false: If failure is expected.
  • exitcodes::AbstractVector{<:Integer}: List of allowed exit codes. xfail is ignored when given.
  • Other keywords are passed to Run.prepare_test.
source
Run.testFunction
Run.test(path="test"; <keyword arguments>)

Run $path/runtests.jl after activating $path/Project.toml. It simply calls Run.script with default keyword arguments code_coverage = true, check_bounds = true, and depwarn = true.

path can also be a path to a script file.

See also Run.script and Run.

source
Run.docsFunction
Run.docs(path="docs"; <keyword arguments>)

Run $path/make.jl after activating $path/Project.toml. It simply calls Run.script.

path can also be a path to a script file.

source
Run.prepareFunction
Run.prepare(path::AbstractString; precompile, parentproject)

Instantiate $path/Project.toml. It also devs the project in the parent directory of path into $path/Project.toml if $path/Manifest.toml does not exist.

Keyword Arguments

  • precompile::Bool = true: Precompile the project if true (default).
  • parentproject::AbstractString: Path to parent project. Default to parent directory of path.
source
Run.migratetestFunction
Run.migratetest(path=".")

Migrate test setup from [targets] in $path/Project.toml to $path/test/Project.toml.

source