micronaut-test-resources-provider-development

Files (1)

• SKILL.md

SKILL.md (first lines)

# Micronaut Test Resources Provider Development

Use this skill when work touches Micronaut Test Resources provider behavior, especially resolver contracts, provider modules, Testcontainers-backed resources, build-tools inference, generated/default Docker images, provider docs, or provider PR follow-through.

## First Read

Before planning or editing:

1. Read the active issue, current execution stage, linked GitHub issue or PR, latest QA or Architect artifact, repo-local `AGENTS.md`, and any `.company-runtime/` overlay.
2. Identify the provider family: standalone provider module, JDBC/R2DBC/Hibernate Reactive database provider, LocalStack split service, build-tools inference, server/client behavior, docs-only provider work, or PR follow-through.
3. Inspect the nearest existing provider implementation and tests before inventing a new pattern.
4. Preserve the target branch, SemVer bar, and organization-project guidance from QA or Architect unless the stage is explicitly returning to planning.

## Provider Contract

Design the provider around the `TestResourcesResolver` lifecycle:

- service-load resolvers through `META-INF/services/io.micronaut.testresources.core.TestResourcesResolver`
- do not depend on normal Micronaut dependency injection; resolvers are loaded before the application context exists
- use `getRequiredPropertyEntries()` when the resolver must enumerate named entries such as datasources
- use `getResolvableProperties(...)` to publish only the properties this resolver can actually provide
- use `getRequiredProperties(String expression)` for prerequisite properties needed before resolving one expression
- make `resolve(...)` and `shouldAnswer(...)` defensive; return `Optional.empty()` for unsupported or insufficiently specified requests
- keep property names, generated values, and fallback behavior stable because build tools and docs consume them as contracts

For Testcontainers-backed providers, prefer `AbstractTestContainersProvider` unless a specialized lifecycle is justified. Define a stable `getSimpleName()`, useful display name, explicit default image, mapped ports, wait strategy, startup timeout, reuse key/query, and cleanup behavior. Use `DockerImageName` compatibility helpers when a Testcontainers module expects a canonical image family but the provider allows a compatible substitute.

## Module And Build Tools

When adding or changing a provider module:

- follow nearby module layout and Gradle convention plugins instead of hand-writing a new structure
- add only the dependencies needed by the provider and its tests
- update build-tools inference when a framework dependency should automatically add the provider to Gradle or Maven test resources
- cover both positive and negative inference cases, including classpath combinations that should not activate the provider
- update BOM or module metadata only when the repository's existing module pattern requires it

When adding a default Docker image, update the default-images manifest in `test-resources-core` and use the generated `DefaultTestResourceImages` constant from provider code. Keep image aliases and provider names aligned with metadata override properties such as `test-resources.containers.<name>.image-name`, and call out any digest, registry, architecture, license, or emulator caveat in the plan or docs.

## Verification

Use the smallest proof that covers the changed surface:

- provider tests for resolvable properties, `shouldAnswer`, required properties, fixed/generated values, metadata overrides, and unsupported-property fallthrough
- startup tests when behavior depends on a real container; if Docker is unavailable, record the exact skipped command and the narrowest non-Docker proof that still ran
- build-tools inference tests when provider activation depends on application dependencies
- service-loader or embedded/server tests when registration or cross-process resolution changed
- docs checks when provider docs, snippets, generated guides, or guide navigation changed
- PR follow-through checks for CI, Sonar, dependency convergence, nullness, flaky provisioning, and unresolved review threads

Do not treat a generic Testcontainers smoke test as enough when the Micronaut resolver contract, build-tools inference, or generated docs changed.

## Documentation

Update docs when users gain or lose provider behavior, configuration, caveats, or dependency requirements:

- add or update the provider module guide under the repository docs structure
- document the dependency coordinate and whether the scope is `testResourcesService`, test runtime, or build-tool inferred
- list the properties the provider resolves and the user-facing configuration overrides
- explain host, mapped-port, TLS/truststore, emulator, image, platform, and Docker requirements that affect successful local use
- include standalone guide follow-up only when the issue or routine asks for a guide path; otherwise keep docs with the provider PR

## Security Review

Treat provider work as security-sensitive when it touches containers, credentials, files, networking, or docs:

- never log real secrets, tokens, connection strings, account keys, truststore passwords, or generated credentials
- distinguish fixed emulator credentials from production credentials in docs and code comments
- avoid binding fixed public host ports; prefer mapped ports and local-only endpoints unless a plan explicitly justifies otherwise
- verify temporary files, truststores, certificates, and mounted resources are scoped and cleaned up
- assess Docker socket exposure, image provenance, registry trust, tag/digest pinning, compatible substitutes, and architecture support
- make reuse keys precise enough to prevent one test's state or credentials from leaking into another incompatible request
- document insecure emulator limitations instead of presenting them as production-safe defaults

## Role Use

- Architect: lock the provider contract, module impacts, docs impact, verification matrix, security-sensitive surfaces, and rollback path.
- Micronaut Engineer: implement the smallest provider, inference, tests, and docs diff that satisfies the approved contract.
- QA Engineer: verify the requested properties resolve through the intended activation path and that unsupported properties do not resolve accidentally.
- Security Engineer: focus on secrets, Docker/image risk, network exposure, filesystem/truststore handling, cleanup, and docs safety.
- Code Reviewer: check resolver lifecycle correctness, Testcontainers reuse/lifecycle details, test strength, docs accuracy, and PR metadata.
- Technical Writer: ensure provider docs describe actual dependencies, resolved properties, overrides, limitations, and guide follow-up.

## Trigger Examples

Use this skill for prompts like:

- "Plan Azure Cosmos emulator support as a Micronaut Test Resources provider."
- "Review the Docker Compose-backed Test Resources service discovery PR."
- "Verify the Kafka Test Resources provider retry and classpath behavior."

Do not use this skill for prompts like:

- "Write a generic Testcontainers tutorial for a standalone Java app."
- "Fix a Micronaut Control Panel UI layout bug."
- "Compare Gradle and Maven plugin parity when no Test Resources provider behavior is involved."

## Completion Checklist

Before handing off or approving provider work, confirm:

- resolver lifecycle methods and service-loader registration match the intended contract
- build-tools inference and dependency metadata are updated or explicitly out of scope
- default image manifest and provider constants are aligned
- provider, inference, startup, docs, and review-thread checks are recorded at the narrowest useful scope
- docs mention user-facing properties, dependencies, and caveats
- security-sensitive container, credential, file, host, and cleanup risks have been reviewed

From alvarosanchez/micronaut-agent-company, MIT.

More from alvarosanchez/micronaut-agent-company