agentleFS
quarkiversequarkiverse/quarkus-langchain4j/.agents/skills/writing-tests/SKILL.md

writing-tests

Skill325 starsChanged 7 days agoApache-2.0View on GitHub

Testing patterns for Quarkus extensions: test annotations, test locations, QuarkusExtensionTest patterns, and how to run tests.

43 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use reviewing-code, commits and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • RiccardoGrinSkill

    reviewing-code

    Runs an adversarial code review loop that spawns independent reviewer and fixer subagents, iterating until only nitpicks remain. Scores findings by confidence, fixes real issues, and re-reviews with fresh eyes — all internal, no GitHub comments. Use when asked to review code, self-review, adversarial review, or polish code before pushing

    Also in 4 projects that use this

  • JetBrainsSkill

    commits

    Use this skill whenever the user asks to commit changes, write or fix a commit message, amend or rename a commit, or do a workflow that includes committing in the IntelliJ repository. This is a thin repo-specific overlay: use IntelliJ commit format, write full commit messages by default, and keep requested suffixes such as IJ-MR trailers in a final separate paragraph.

    Also in 3 projects that use this

  • OpenAISkill

    running-tests

    Guide for running tests in the openai-dotnet repository. Use this when asked to run, debug, or validate tests, or when writing new tests. Explains test modes (Playback, Record, Live), how to identify recorded vs non-recorded tests, environment variable configuration, and what to do when recordings are missing or stale.

    Also in 3 projects that use this

  • BlockSkill

    debugging

    Debugging guidelines and best practices

    Also in 6 projects that use this

  • sahinSkill

    execute

    Also in 3 projects that use this

  • stericishereSkill

    graphify

    any input (code, docs, papers, images) → knowledge graph → clustered communities → HTML + JSON + audit report

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. 0 are common, 5 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 43 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never add a new QuarkusUnitTest.

    line 25
  2. Very specific:

    When writing these tests, if Quarkus configuration needs to be specified, prefer the overrideConfigKey and overrideRuntimeConfigKey methods …

    line 27
  3. Very specific:

    If the tests have to set Quarkus configuration, then using QuarkusExtensionTest#overrideConfigKey for build time configuration and …

    line 50
  4. Very specific:

    If the module has no AssertJ on its test classpath, you can add the dependency.

    line 99
  5. Very specific:

    Use the assertion that names the check, because its failure message shows the values: containsEntry(key, value) instead of get(key) and …

    line 110
  6. Very specific:

    Use RestAssured for HTTP endpoint testing.

    line 117
  7. Distinctive:

    When a fix depends on configuration, test each combination of the properties that it reads, and the case where none is set.

    line 122
  8. Very specific:

    Before you write a test helper, look in the module's test sources and in the test utilities of the extension, for example …

    line 136
  9. Very specific:

    Do not use java.net.http.HttpClient or a raw Socket.

    line 139
  10. Very specific:

    Do not start a com.sun.net.httpserver.HttpServer as a test server.

    line 142
  11. Distinctive:

    Use Mockito mocks only as a last resort.

    line 145
  12. Very specific:

    Do not use Thread.sleep to wait for a result.

    line 151
  13. Very specific:

    Do NOT use @QuarkusTest in deployment module tests — use QuarkusExtensionTest

    line 160
  14. Distinctive:

    Use RestAssured for HTTP endpoint testing

    line 162
  15. Distinctive:

    Test in both JVM and native mode for non-trivial changes

    line 163
  16. Distinctive:

    Verify that build-time errors produce clear, actionable error messages

    line 165
  17. Very specific:

    Wait with await().atMost(timeout) on every request.

    line 184
  18. Very specific:

    Create the WebClient in the test that uses it, and close it at the end of that test, in a finally block or in @AfterEach.

    line 186

“Common” is measured: kept by at least 6 in 10 of the 43 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing Tests

Quarkus uses JUnit 5 with custom extensions. Tests and documentation are mandatory for contributions.

Test Annotations

  • @QuarkusTest — Starts a full Quarkus application. Use for integration tests in integration-tests/.
  • @QuarkusIntegrationTest — Tests against a built artifact (JAR or native binary). In the main repo, most run only with -Dnative.

Test Extensions (used with @RegisterExtension)

  • QuarkusExtensionTest — Used in deployment module tests. Creates a synthetic application defined in the test. This is the primary way to test build-time behavior. Replaces the deprecated QuarkusUnitTest.
    • Never add a new QuarkusUnitTest. When you edit a test that still uses it, move it to QuarkusExtensionTest in the same change.
    • When writing these tests, if Quarkus configuration needs to be specified, prefer the overrideConfigKey and overrideRuntimeConfigKey methods of QuarkusExtensionTest
  • QuarkusDevModeTest — Tests hot reload / dev mode behavior.

Test Location

  • Extension tests for deployment logic: extensions/<name>/deployment/src/test/
  • Integration tests needing a running app: integration-tests/
  • Deployment module tests use QuarkusExtensionTest, NOT @QuarkusTest

QuarkusExtensionTest Pattern

@RegisterExtension
static final QuarkusExtensionTest config = new QuarkusExtensionTest()
    .withApplicationRoot((jar) -> jar
        .addClasses(MyResource.class, MyService.class));

@Test
void testFeature() {
    // test with RestAssured or similar
}

If the tests have to set Quarkus configuration, then using QuarkusExtensionTest#overrideConfigKey for build time configuration and QuarkusExtensionTest#overrideRuntimeConfigKey for runtime configuration is preferable.

Running Tests

# Run tests for an extension
./mvnw verify -f extensions/<name>/

# Run a single test class
./mvnw test -f integration-tests/<name>/ -Dtest=MyTest

# Run a single test method
./mvnw verify -Dtest=fully.qualified.ClassName#methodName

# Native integration tests
./mvnw verify -f integration-tests/<name>/ -Dnative

Native Test Registration

Native tests are split into parallel categories for CI performance. Each new integration test module must be registered in .github/native-tests.json to have its native tests run in CI. Without this, -Dnative tests will not execute for the module.

Note: @QuarkusIntegrationTest tests in the main repo only run when -Dnative is passed — even verify with -DskipITs=false will not trigger them.

MicroProfile TCK Tests

The tcks/ module contains MicroProfile TCK tests (Config, JWT, Fault Tolerance, Health, Metrics, OpenAPI, Telemetry, REST Client, Reactive Messaging, Context Propagation). If your work touches any of these areas, run the TCKs:

# Run all TCKs
./mvnw verify -f tcks/ -Ptcks

# Run a specific TCK
./mvnw verify -f tcks/<area>/ -Ptcks

Assertions

  • Prefer AssertJ (org.assertj.core.api.Assertions.assertThat) over JUnit 5 assertions (org.junit.jupiter.api.Assertions). AssertJ provides fluent, readable assertions and better failure messages.
  • If the module has no AssertJ on its test classpath, you can add the dependency. build-parent manages the version, so the dependency needs no <version>:

    <dependency>
        <groupId>org.assertj</groupId>
        <artifactId>assertj-core</artifactId>
        <scope>test</scope>
    </dependency>
  • Use the assertion that names the check, because its failure message shows the values: containsEntry(key, value) instead of get(key) and isEqualTo, hasSize(2) instead of size() and isEqualTo(2), assertThatThrownBy(...) or assertThatExceptionOfType(...) instead of assertThrows.
  • A bare isTrue() fails with "expected true". Assert the value itself, or describe the check with as("...").
  • Use RestAssured for HTTP endpoint testing. Its Hamcrest matchers in body(...) are fine.

What a Test Covers

  • When a fix depends on configuration, test each combination of the properties that it reads, and the case where none is set. For example, a fix that reads a TLS configuration name and credentials needs four tests: both set, the name only, the credentials only, and neither.
  • Also test the error paths, for example the status code when the request body is missing.
  • Assert what the user sees: the response body, the content type or the message text. A request that does not fail does not prove the fix.
  • A streaming test sends more data than the heap of the test JVM. With a small payload, the test also passes when the code buffers all the data in memory.

Test Utilities and Resources

  • Before you write a test helper, look in the module's test sources and in the test utilities of the extension, for example io.quarkus.micrometer.test.Util. Reuse them.
  • Do not use java.net.http.HttpClient or a raw Socket. Use RestAssured, the client of the module such as the WebSockets Next WSClient, or the Vert.x client.
  • Do not start a com.sun.net.httpserver.HttpServer as a test server. Serve the endpoint from the test application: a Jakarta REST resource or a route that observes the Vert.x Router. A Vert.x HTTP server is also fine.
  • Use Mockito mocks only as a last resort. A test that mocks the Quarkus code under test does not prove that the feature works. Test the real code in an application instead.
  • To test a client of a remote service, mock the remote server with WireMock, org.wiremock:wiremock-standalone. build-parent manages its version. WireMock replaces the server, not the Quarkus code.
  • Do not use Thread.sleep to wait for a result. Wait for the condition with Awaitility: await().atMost(...).untilAsserted(...).
  • Close every client and server that a test creates. Use try-with-resources when the type is AutoCloseable. Otherwise close it in @AfterEach or @AfterAll, in the same lifecycle that created it. An open client keeps its Vert.x instance and its threads.

Key Rules

  • Do NOT use @QuarkusTest in deployment module tests — use QuarkusExtensionTest
  • Integration tests belong in integration-tests/, not in extension modules
  • Use RestAssured for HTTP endpoint testing
  • Test in both JVM and native mode for non-trivial changes
  • New native tests must be registered in .github/native-tests.json
  • Verify that build-time errors produce clear, actionable error messages
  • Container engine (Docker/Podman) is needed for dev-services tests
  • Parallel test execution is not supported
  • When writing a test that verifies a bug has been fixed, ensure that the test has run against the code that does not contain the fix and verify this test fails. This provides some confidence that the test does actually verify the fix; in other words, this addresses the never trust a test you haven't seen fail adage
  • A fix must not change the behavior of paths it does not target. Test those paths too, and assert the behavior of main. Run the test class on main and with the fix: only the tests of the fixed path may differ.

HTTP Clients Other Than RestAssured

RestAssured uses Apache HttpClient 4, which has no HTTP/2 support. rest-assured/rest-assured#1696 tracks the move to HttpClient 5. Until RestAssured supports HTTP/2, use the Mutiny Vert.x web client for HTTP/2, h2c or other protocol-level tests:

  • Add io.smallrye.reactive:smallrye-mutiny-vertx-web-client with test scope. The Quarkus BOM manages its version.
  • Inject the managed io.vertx.mutiny.core.Vertx. Do not create a Vert.x instance in the test.
  • Wait with await().atMost(timeout) on every request. Do not use CompletableFuture or UniHelper.
  • Create the WebClient in the test that uses it, and close it at the end of that test, in a finally block or in @AfterEach. The Mutiny WebClient is not AutoCloseable. The protocol is an option of the WebClient, not of a request. A test of another protocol creates its own client.
  • In Vert.x 5, the Mutiny web client uses io.vertx.core.buffer.Buffer.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.