Write JETLS tests

Use this skill when you add new tests or modify existing JETLS test code.

Test file structure

Test code for new language server features should be written in files that define independent module spaces with a test_ prefix. Include those files from JETLSCore/test/runtests.jl.

This lets each test file run independently from the REPL.

For example, JETLSCore/test/test_completions.jl should look like:

module test_completions
using Test
...
end # module test_completions

Then include it from JETLSCore/test/runtests.jl like this:

@testset "JETLS.jl" begin
    ...
    @testset "completions" include("test_completions.jl")
    ...
end

Organizing test code

Use @testset "testset name" to organize tests cleanly.

For code clarity, avoid placing using, import, or struct definitions inside @testset blocks unless it is specifically necessary. Prefer top-level definitions.

Use let blocks to avoid unintentionally reusing names across test cases, unless a helper function or do block already provides local scope.

Example:

module test_completions

using Test
using JETLSCore: some_completion_func

function testcase_util(s::AbstractString)
    ...
end
function with_testcase(s::AbstractString)
    ...
end

@testset "some_completion_func" begin
    let s = "..."
        ret = some_completion_func(testcase_util(s))
        @test test_with(ret)
    end
    let s = "..."
        ret = some_completion_func(testcase_util(s))
        @test test_with(ret)
    end

    with_testcase(s) do case
        ret = some_completion_func(case)
        @test test_with(ret)
    end
end

end # module test_completions

Language-server feature tests

Testing language server functionality is challenging. To fully test such functionality, you need to start a server loop and send requests that mimic realistic user interactions.

For those tests, use withserver from JETLSCore/test/setup.jl. Refer to JETLSCore/test/test_full_lifecycle.jl as an example.

A good pattern is JETLSCore/test/test_definition.jl: it keeps the full withserver coverage to one request/response sanity test for the DidOpen → analysis → DefinitionRequest path, while most cases use definition_test to call find_definition directly and assert on returned locations. Prefer this split for LSP handlers.

Cached syntax trees

Requests on a synchronized document share the cached syntax tree of its FileInfo without copying it, so no feature may mutate that tree. Under JETLS_TEST_MODE, JETLS records a fingerprint of each cached tree and JETLSCore.check_syntax_tree0(fi) throws if the tree has changed since. withserver runs this check for every open document when the test finishes.

Helpers that construct their own FileInfo and call a feature directly should construct it with cache_tree0 = true, as cache_file_info! does for synchronized documents, and call JETLSCore.check_syntax_tree0(fi) after the feature call:

function find_definition(text::AbstractString, pos::Position)
    server = JETLSCore.Server()
    filename = joinpath(@__DIR__, "testfile_$(gensym(:definition)).jl")
    fi = JETLSCore.FileInfo(#=version=#0, text, filename; cache_tree0 = true)
    furi = filename2uri(filename)
    JETLSCore.store!(server.state.file_cache) do cache
        Base.PersistentDict(cache, furi => fi), nothing
    end
    result = JETLSCore.find_definition(server, furi, fi, pos)
    JETLSCore.check_syntax_tree0(fi)
    return result
end

Leave cache_tree0 unset when the FileInfo is only used to convert positions or stands for a file that is not open in the editor, since JETLS doesn't cache a tree for such files in production either.

After writing tests

When you add or modify tests, use the run-test workflow to run the most specific relevant test command.