Julia Test Items

https://julia-testitems.org/
Admin
Julia Test Items is a modern testing framework for Julia that allows writing standalone test items...
Tokens:4,250
Snippets:73
Trust Score:2.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install and Load TestItemREPL.jl

Source: https://julia-testitems.org/guide/repl

Install the package via Pkg and load it into the current Julia session.

```julia
using Pkg
Pkg.add(url="https://github.com/julia-testitem/TestItemREPL.jl")
```

```julia
using TestItemREPL
```

--------------------------------

### Define and use a test snippet

Source: https://julia-testitems.org/guide/writing-tests

Uses @testsnippet to define reusable setup code that is inlined into test items via the setup keyword.

```julia
@testsnippet DatabaseSetup begin
    db = connect_to_test_database()
    populate_test_data!(db)
end

@testitem "Query tests" setup=[DatabaseSetup] begin
    results = query(db, "SELECT * FROM users")
    @test length(results) > 0
end
```

--------------------------------

### Configure test runner with included files

Source: https://julia-testitems.org/guide/writing-tests

Example of a runtests.jl file that includes test files for parsing and syntax validation.

```julia
# test/runtests.jl
using TestItemRunner

@run_package_tests

include("test_foo.jl")
include("test_bar.jl")
```

--------------------------------

### Install TestItems.jl

Source: https://julia-testitems.org/guide/getting-started

Add the TestItems package to your Julia project using the Pkg manager.

```julia
using Pkg
Pkg.add("TestItems")
```

--------------------------------

### Define and use a test module

Source: https://julia-testitems.org/guide/writing-tests

Uses @testmodule for expensive setup that runs once per process and is shared across test items.

```julia
@testmodule HeavySetup begin
    const LARGE_DATASET = load_dataset("testdata/large.csv")
end

@testitem "Dataset tests" setup=[HeavySetup] begin
    @test length(HeavySetup.LARGE_DATASET) > 1000
end
```

--------------------------------

### Show Help

Source: https://julia-testitems.org/guide/repl

Display a summary of all available commands.

```text
test> help
```

--------------------------------

### help / ?

Source: https://julia-testitems.org/guide/repl

Show a summary of all available commands.

```APIDOC
## help / ?

### Description
Show a summary of all available commands.

### Usage
`test> help`
```

--------------------------------

### Enter Test REPL Mode

Source: https://julia-testitems.org/guide/repl

Switch from the standard julia prompt to the test REPL mode.

```text
julia> )
test>
```

--------------------------------

### run

Source: https://julia-testitems.org/guide/repl

Run tests synchronously, blocking the REPL until complete.

```APIDOC
## run

### Description
Run tests synchronously, blocking the REPL until complete. Press Esc to cancel.

### Usage
`test> run [+channel] [path] [--workers=N] [--timeout=S] [--tags=tag1,tag2] [--coverage]`

### Parameters
- **+channel** (string) - Optional - Juliaup channel to use (e.g., +lts, +release, +nightly).
- **path** (string) - Optional - Directory or partial test item name to filter by.
- **--workers** (integer) - Optional - Number of parallel worker processes. Default: min(Sys.CPU_THREADS, 8).
- **--timeout** (integer) - Optional - Per-test-item timeout in seconds. Default: 300.
- **--tags** (string) - Optional - Filter by tags.
- **--coverage** (flag) - Optional - Enable code coverage measurement.
```

--------------------------------

### list / ls

Source: https://julia-testitems.org/guide/repl

Discover and list all test items in a project.

```APIDOC
## list / ls

### Description
Discover and list all test items in a project.

### Usage
`test> list [path] [--tags=tag1,tag2]`

### Parameters
- **path** (string) - Optional - Directory to scan. Defaults to the current working directory.
- **--tags** (string) - Optional - Filter by tags (comma-separated).
```

--------------------------------

### Configure runtests.jl

Source: https://julia-testitems.org/guide/cli

Initialize test item discovery by adding the macro to your test runner file.

```julia
using TestItemRunner

@run_package_tests
```

--------------------------------

### List Test Items

Source: https://julia-testitems.org/guide/repl

Discover and list test items in the project directory.

```text
test> list [path] [--tags=tag1,tag2]
```

--------------------------------

### Run Tests Synchronously

Source: https://julia-testitems.org/guide/repl

Execute tests and block the REPL until completion.

```text
test> run [+channel] [path] [--workers=N] [--timeout=S] [--tags=tag1,tag2] [--coverage]
```

```text
test> run
test> run /path/to/myproject
test> run +lts --workers=4 --timeout=60
test> run --tags=unit,fast
```

--------------------------------

### run&

Source: https://julia-testitems.org/guide/repl

Run tests asynchronously in the background.

```APIDOC
## run&

### Description
Run tests asynchronously in the background. The REPL remains interactive so you can continue working.

### Usage
`test> run& [same options as run]`
```

--------------------------------

### Configure Julia CI Workflow

Source: https://julia-testitems.org/guide/ci

Add this file to .github/workflows/juliaci.yml to enable automated testing, documentation deployment, and maintenance tasks.

```yaml
name: Julia CI

on:
  push: {branches: [main, master]}
  pull_request: {types: [opened, synchronize, reopened, ready_for_review, converted_to_draft]}
  issue_comment: {types: [created]}
  schedule: [{cron: '0 0 * * *'}]
  workflow_dispatch:
    inputs:
      feature:
        type: choice
        description: What to run
        options: [CompatHelper, DocDeploy, LintAndTest, TagBot]

jobs:
  julia-ci:
    uses: julia-testitems/testitem-workflow/.github/workflows/juliaci.yml@v1
    permissions: write-all
    secrets:
      codecov_token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Include Release Candidates in CI

Source: https://julia-testitems.org/guide/ci

Enable testing against release candidate versions by setting the include-rc-versions option to true.

```yaml
jobs:
  julia-ci:
    uses: julia-testitems/testitem-workflow/.github/workflows/juliaci.yml@v1
    with:
      include-rc-versions: true
    permissions: write-all
    secrets:
      codecov_token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### View Process Logs

Source: https://julia-testitems.org/guide/repl

Display raw output logs for a specific test process.

```text
test> process-log <process_id>
```

--------------------------------

### status / st

Source: https://julia-testitems.org/guide/repl

Show progress of the current background test run.

```APIDOC
## status / st

### Description
Show progress of the current background test run. Displays elapsed time and live counts of passed, failed, errored, and skipped tests.

### Usage
`test> status`
```

--------------------------------

### Run Tests on Different Julia Versions

Source: https://julia-testitems.org/guide/repl

Specify a Juliaup channel to run tests against different versions.

```text
test> run +lts
test> run +release
test> run +nightly
```

--------------------------------

### Run Tests Asynchronously

Source: https://julia-testitems.org/guide/repl

Execute tests in the background while keeping the REPL interactive.

```text
test> run& [same options as run]
```

--------------------------------

### process-log / plog

Source: https://julia-testitems.org/guide/repl

Display the raw output log from a specific test process.

```APIDOC
## process-log / plog

### Description
Display the raw output log from a specific test process.

### Usage
`test> process-log <process_id>`

### Parameters
- **process_id** (string) - Required - The ID of the test process.
```

--------------------------------

### Configure Parallel Execution

Source: https://julia-testitems.org/guide/repl

Adjust the number of worker processes for test execution.

```text
test> run --workers=4
test> run --workers=1   # serial execution
```

--------------------------------

### Define a basic test item

Source: https://julia-testitems.org/guide/writing-tests

Creates an independent test block using the @testitem macro.

```julia
@testitem "My test" begin
    @test 1 + 1 == 2
end
```

--------------------------------

### Define a Test Item

Source: https://julia-testitems.org/guide/getting-started

Create a self-contained test block using the @testitem macro. By default, Test and the package being tested are automatically imported.

```julia
@testitem "First tests" begin
    x = foo("bar")

    @test length(x) == 3
    @test x == "bar"
end
```

--------------------------------

### Display Test Results

Source: https://julia-testitems.org/guide/repl

View results from a completed test run.

```text
test> results [id] [--name=pattern] [--verbose] [--output]
```

--------------------------------

### Add TestItemRunner as a test dependency

Source: https://julia-testitems.org/guide/cli

Use the Pkg manager to add TestItemRunner to the test environment of your package.

```julia
# In your package directory
using Pkg
Pkg.activate("test")
Pkg.add("TestItemRunner")
```

--------------------------------

### Override CI Configuration for Draft PRs

Source: https://julia-testitems.org/guide/ci

Use the draft-pr- prefix to apply specific configuration overrides when a pull request is in a draft state.

```yaml
jobs:
  julia-ci:
    uses: julia-testitems/testitem-workflow/.github/workflows/juliaci.yml@v1
    with:
      draft-pr-include-lts-versions: false
      draft-pr-include-windows-x64: false
      draft-pr-include-windows-x86: false
      draft-pr-include-linux-x86: false
      draft-pr-include-macos-x64: false
      draft-pr-include-macos-aarch64: false
    permissions: write-all
    secrets:
      codecov_token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Define inline test items

Source: https://julia-testitems.org/guide/writing-tests

Places test items directly within the source code module, requiring the TestItems dependency.

```julia
module MyPackage

using TestItems

export foo

foo(x) = x

@testitem "foo tests" begin
    @test foo("bar") == "bar"
    @test length(foo("bar")) == 3
end

end
```

--------------------------------

### Monitor Background Run Status

Source: https://julia-testitems.org/guide/repl

Check the progress of an active background test run.

```text
test> status
```

--------------------------------

### Categorize tests with tags

Source: https://julia-testitems.org/guide/writing-tests

Assigns symbols to test items for filtering during execution in VS Code, CLI, or CI.

```julia
@testitem "Database tests" tags=[:slow, :database] begin
    # ...
end

@testitem "Unit tests" tags=[:fast] begin
    # ...
end
```

--------------------------------

### Disable default imports in test items

Source: https://julia-testitems.org/guide/writing-tests

Configures a test item to skip automatic imports, requiring manual inclusion of necessary modules.

```julia
@testitem "No default imports" default_imports=false begin
    using MyPackage, Test

    @test foo("bar") == "bar"
end
```

--------------------------------

### Define a standalone test item

Source: https://julia-testitems.org/

Use the @testitem macro to create a self-contained test block with optional tags for filtering.

```julia
@testitem "CSV parsing" tags=[:parser] begin
    data = parsecsv("name,age\nAlice,30\nBob,25")

    @test length(data) == 2
    @test data[1].name == "Alice"
    @test data[2].age == 25
end
```

--------------------------------

### results / res

Source: https://julia-testitems.org/guide/repl

Display test results from the last completed run, or a specific run by ID.

```APIDOC
## results / res

### Description
Display test results from the last completed run, or a specific run by ID.

### Usage
`test> results [id] [--name=pattern] [--verbose] [--output]`

### Parameters
- **id** (string) - Optional - Run ID to display (supports prefix matching). Defaults to the last run.
- **--name** (string) - Optional - Filter by test item name (case-insensitive substring match).
- **--verbose** (flag) - Optional - Show full per-profile details including messages and output.
- **--output** (flag) - Optional - Show only captured stdout/stderr for each test item.
```

--------------------------------

### cancel

Source: https://julia-testitems.org/guide/repl

Cancel an active background test run.

```APIDOC
## cancel

### Description
Cancel an active background test run.

### Usage
`test> cancel [run_id]`

### Parameters
- **run_id** (string) - Optional - The ID of the specific run to cancel. If omitted, cancels the current active run.
```

--------------------------------

### Filter test items

Source: https://julia-testitems.org/guide/cli

Apply filtering logic to test execution using test item metadata.

```julia
using TestItemRunner

# Skip tests tagged :skipci
@run_package_tests filter=ti->!(:skipci in ti.tags)
```

```julia
# Run only tests tagged :fast
@run_package_tests filter=ti->(:fast in ti.tags)

# Run tests from a specific file
@run_package_tests filter=ti->(endswith(ti.filename, "test_foo.jl"))

# Combine conditions
@run_package_tests filter=ti->(!(:skipci in ti.tags) && endswith(ti.filename, "test_foo.jl"))
```

--------------------------------

### Cancel Test Run

Source: https://julia-testitems.org/guide/repl

Stop an active background test run by ID or the current run.

```text
test> cancel [run_id]
```
Tokens:
Raw