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
- chrisezedi/claude-skillstheir own version, first seen Nov 16, 2026
- RMATI-11861/Claude-Skillstheir own version, first seen Nov 16, 2026
- ekirton/Pouletheir own version, first seen Nov 15, 2026
- ZaxbyHub/opencode-swarmtheir own version, first seen Nov 15, 2026
- iliaal/ai-skillstheir own version, first seen Nov 14, 2026
- PostHog/posthogtheir own version, first seen Nov 14, 2026
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.
RiccardoGrinSkillreviewing-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
JetBrainsSkillcommits
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
OpenAISkillrunning-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
BlockSkilldebugging
Debugging guidelines and best practices
Also in 6 projects that use this
sahinSkillexecute
Also in 3 projects that use this
stericishereSkillgraphify
any input (code, docs, papers, images) → knowledge graph → clustered communities → HTML + JSON + audit report
Also in 3 projects that use this
Other versions43 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- quarkusio/quarkus★ 16k100% same
Wrote their own version · 42
- remotion-dev/remotion★ 73ksame name
- PostHog/posthog★ 41ksame name
- JetBrains/intellij-community★ 21ksame name
- mcp-use/mcp-use★ 11ksame name
- DetachHead/rebased★ 6.5ksame name
- chattocorp/chatto★ 3ksame name
- starkware-libs/cairo★ 1.9ksame name
- bholmesdev/hubble.md★ 1.5ksame name
- amplifthq/openmeld★ 1.4ksame name
- amplifthq/opentag★ 1.4ksame name
32 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- coding-styleSkill
- pull-requestsSkill
- working-with-configSkill
- writing-build-stepsSkill
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
- Very specific: line 25
Never add a new QuarkusUnitTest.
- Very specific: line 27
When writing these tests, if Quarkus configuration needs to be specified, prefer the overrideConfigKey and overrideRuntimeConfigKey methods …
- Very specific: line 50
If the tests have to set Quarkus configuration, then using QuarkusExtensionTest#overrideConfigKey for build time configuration and …
- Very specific: line 99
If the module has no AssertJ on its test classpath, you can add the dependency.
- Very specific: line 110
Use the assertion that names the check, because its failure message shows the values: containsEntry(key, value) instead of get(key) and …
- Very specific: line 117
Use RestAssured for HTTP endpoint testing.
- Distinctive: line 122
When a fix depends on configuration, test each combination of the properties that it reads, and the case where none is set.
- Very specific: line 136
Before you write a test helper, look in the module's test sources and in the test utilities of the extension, for example …
- Very specific: line 139
Do not use java.net.http.HttpClient or a raw Socket.
- Very specific: line 142
Do not start a com.sun.net.httpserver.HttpServer as a test server.
- Distinctive: line 145
Use Mockito mocks only as a last resort.
- Very specific: line 151
Do not use Thread.sleep to wait for a result.
- Very specific: line 160
Do NOT use @QuarkusTest in deployment module tests — use QuarkusExtensionTest
- Distinctive: line 162
Use RestAssured for HTTP endpoint testing
- Distinctive: line 163
Test in both JVM and native mode for non-trivial changes
- Distinctive: line 165
Verify that build-time errors produce clear, actionable error messages
- Very specific: line 184
Wait with await().atMost(timeout) on every request.
- Very specific: line 186
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.
“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.
Files
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 inintegration-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 deprecatedQuarkusUnitTest.- Never add a new
QuarkusUnitTest. When you edit a test that still uses it, move it toQuarkusExtensionTestin the same change. - When writing these tests, if Quarkus configuration needs to be specified, prefer the
overrideConfigKeyandoverrideRuntimeConfigKeymethods ofQuarkusExtensionTest
- Never add a new
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>/ -DnativeNative 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>/ -PtcksAssertions
- 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-parentmanages 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 ofget(key)andisEqualTo,hasSize(2)instead ofsize()andisEqualTo(2),assertThatThrownBy(...)orassertThatExceptionOfType(...)instead ofassertThrows. - A bare
isTrue()fails with "expected true". Assert the value itself, or describe the check withas("..."). - 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.HttpClientor a rawSocket. Use RestAssured, the client of the module such as the WebSockets NextWSClient, or the Vert.x client. - Do not start a
com.sun.net.httpserver.HttpServeras a test server. Serve the endpoint from the test application: a Jakarta REST resource or a route that observes the Vert.xRouter. 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-parentmanages its version. WireMock replaces the server, not the Quarkus code. - Do not use
Thread.sleepto 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@AfterEachor@AfterAll, in the same lifecycle that created it. An open client keeps its Vert.x instance and its threads.
Key Rules
- Do NOT use
@QuarkusTestin deployment module tests — useQuarkusExtensionTest - 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 failadage - 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 onmainand 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-clientwithtestscope. 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 useCompletableFutureorUniHelper. - Create the
WebClientin the test that uses it, and close it at the end of that test, in afinallyblock or in@AfterEach. The MutinyWebClientis notAutoCloseable. The protocol is an option of theWebClient, 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.
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
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.

