reportAwsEmulator captures resources currently present in an existing emulator, including resources created by Gradle tasks, CloudFormation, application code, or SDK calls. It uses the selected runtime’s region, credentials, and verified HTTPS connection.
Inspect A Development Instance
./gradlew reportAwsEmulator
./gradlew reportAwsEmulator --runtime integration
Start or provision the selected development instance first. Reporting never builds an image, starts or restarts an owned container, seeds resources, or changes resource state. An absent, stopped, or unhealthy instance fails the task with a connection diagnostic. An instance whose settings no longer match the build must be restarted before reporting.
When setup and reporting share a Gradle invocation, declare the intended order with dependsOn, mustRunAfter, or a finalizer so the snapshot runs after provisioning.
Each named runtime also has a fixed task, such as reportAwsEmulatorIntegration. With shared ownership, the report inspects the owner’s selected runtime and writes artifacts in the invoking project. With an external connection, it connects using the supplied files without invoking Docker or managing lifecycle.
Output And Coverage
Both formats are written from the same snapshot:
-
index.html: a standalone, offline report with service navigation, expandable configuration, and collection issues. -
report.json: machine-readable data withschemaVersion: 1,capturedAt,runtime, andservices.
All 13 service sections are included on every report. The eight additional sections extend schema version 1 without changing the existing sections. JSON consumers should select sections by service name rather than array position or a fixed section count. The service names in the table below are the exact JSON names.
The default directory is build/reports/aws-emulator/<runtime>/<mode>/<taskName>/, where mode is lowercase. For the default task, open build/reports/aws-emulator/default/development/reportAwsEmulator/index.html. The task prints both paths. Distinct runtime, mode, and task directories allow several snapshots in one build.
| Service | Collected metadata |
|---|---|
S3 |
Bucket names, ARNs, creation dates, regions, and versioning/MFA-delete settings. |
SQS |
Queue names and URLs, ARNs, visibility/delay/retention settings, FIFO and deduplication attributes, encryption identifiers, redrive policies, and approximate message counts. |
SNS |
Topic ARNs and settings, subscription counts, and subscription ARNs, protocols, and SQS/Lambda target endpoints. Other endpoint values are omitted. |
DynamoDB |
Table ARNs and status, key schemas and attribute types, billing mode and table throughput, secondary indexes and projections, stream settings, and service-reported item/size counts. |
CloudFormation |
Non-deleted stack names, IDs, status and timestamps, parameter/output names, and logical-to-physical resource mappings with resource types and statuses. |
EventBridge |
Event bus names and ARNs; nested rule names, ARNs, state, schedules, roles, and managed-by identifiers; target IDs, ARNs, roles, retry settings, and dead-letter ARNs. |
Kinesis |
Stream names, ARNs, status, creation times, capacity mode, open shard/consumer counts, retention hours, and encryption type/key identifiers. |
SSM |
Parameter names, types, tiers, data types, versions, encryption key identifiers, and modification times from |
Secrets Manager |
Secret names and ARNs, encryption key identifiers, rotation status/Lambda ARNs, primary region, owning service, and creation/change/rotation/deletion times from |
KMS |
Key IDs, ARNs, state, enabled status, specification, usage, manager, origin, multi-region flag, and creation/deletion times; alias names, ARNs, target key IDs, and timestamps. |
CloudWatch Logs |
Log group names, ARNs, creation times, retention, stored bytes, encryption keys, and class; nested log stream names, ARNs, creation/event/ingestion times, and stored bytes. |
Cognito |
User pool IDs, names, ARNs, status, MFA/deletion-protection settings, username/alias attributes, and estimated user counts; app client IDs/names, auth/OAuth settings and token validity; group names, roles, precedence, and timestamps. |
SES |
Email identity names/types, sending/verification status, feedback-forwarding setting, DKIM status, and MAIL FROM domains; configuration sets with event destination names, enabled state, event types, and SNS/EventBridge/Firehose ARNs; template names and creation times. |
The report queries each service’s metadata APIs and follows all response pages, including nested rule, target, log stream, client, and group listings. It includes the selected region’s results and service-global resources returned by those APIs; it does not scan other regions. Counts refer to top-level resources: buckets, queues, topics, tables, stacks, event buses, streams, parameters, secrets, KMS keys and aliases, log groups, user pools, and SES identities/configuration sets/templates. Nested relationships do not increase the section’s resource count.
Services can return default resources that no task explicitly created, such as the default EventBridge bus and predefined KMS aliases. KMS aliases without a target key are included as returned; the report never resolves those aliases with DescribeKey, which could materialize a default key. Existing KMS keys are described only by IDs obtained from ListKeys.
Object contents, message bodies, table items, Kinesis records, log events, credentials, parameter/secret values, CloudFormation templates and parameter/output values, Cognito users/passwords/client secrets/tokens, and SES email/template contents are excluded. EventBridge event patterns, target inputs/input paths/transforms, arbitrary tags/descriptions/policies, Cognito callback/logout URLs, and log upload tokens are also omitted by the new collectors. Resource names, identifiers, group names, and SES identity addresses remain visible.
Reporting never receives SQS messages, scans DynamoDB items, opens Kinesis shard iterators, reads log events, fetches or decrypts parameter/secret values, lists Cognito users, retrieves SES template contents, or sends email. Collection happens over several requests, so concurrently changing resources may produce an incomplete snapshot. Counts and timestamps may be approximate or delayed.
The selected connection must allow the metadata operations in the coverage table. Cognito client details use DescribeUserPoolClient with an explicit output field list; its client secret and callback/logout URLs are discarded. SES uses GetEmailIdentity and GetConfigurationSetEventDestinations alongside the list APIs. Missing permissions or unsupported operations use the same partial-report behavior as the original five services.
The pinned emulator 1.0.385 implements SES v2 ListEmailTemplates, so reports inventory template names and metadata without retrieving their contents. Older versions such as 1.0.322 return an unsupported operation: reports then record UNSUPPORTED, retain available SES identity/configuration-set metadata, and continue collecting the other services. An empty template list is not assumed when listing fails. SES v1 listing is not used as a fallback because this emulator stores its v1 and v2 templates separately.
Collection runs in a Gradle worker JVM with Kinesis’s JSON wire format enabled. The worker uses the selected connection’s explicit endpoint, credentials, and verified TLS configuration. It does not change the Gradle daemon’s SDK settings.
Collection Errors
Each service has a status:
-
COMPLETE: all attempted queries succeeded, including an empty inventory. -
PARTIAL: some resources were captured, but one or more queries failed. -
FAILED: collection failed before any resource was captured.
Issues include the operation, affected resource when known, error category (ERROR or UNSUPPORTED), and exception type or service error code. Raw response bodies and exception messages are omitted. A repeated pagination token stops that listing and records an issue. Other service sections and resource metadata queries continue.
By default, partial reports are written with a warning and the task succeeds. To fail the build after writing both files:
./gradlew reportAwsEmulator --fail-on-error
--fail-on-error succeeds when all sections are complete and fails after writing the reports when any operation is unsupported or fails. Omit the flag to retain the default warning-and-report behavior.
Connection and filesystem errors always fail the task. Previous index.html and report.json files in the task’s report directory are removed before connecting, so a failed connection cannot leave a previous successful report at those paths. Archive reports elsewhere when retaining multiple runs.
Capture A Managed Test Instance
Register a typed report and attach it as a finalizer to the existing participating test task. Select the same runtime and MANAGED mode:
import io.github.gregwhitaker.awsemulator.emulator.ReportAwsEmulatorTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
val reportIntegrationEmulator = tasks.register<ReportAwsEmulatorTask>("reportIntegrationEmulator") {
runtimeName.set("integration")
mode.set(EmulatorMode.MANAGED)
}
tasks.named<Test>("integrationTest") {
finalizedBy(reportIntegrationEmulator)
}
This assumes integrationTest already participates in the named integration runtime through awsEmulator.useWith(…). The finalizer captures state after ordinary test successes and failures, before the shared build service removes its managed instance. It keeps resource setup and test execution explicit. If the runtime was never started, reporting fails with a diagnostic and does not start an empty instance. A hard-killed Gradle process cannot run finalizers.
A managed report can only inspect the instance owned by the current build. Running reportAwsEmulator --mode MANAGED in a later invocation cannot recover a previous build’s removed resources.
The basic example offers this finalizer with -PemulatorReport:
./gradlew -p examples/basic integrationTest -PemulatorReport --configuration-cache
The services example exercises SSM, Secrets Manager, EventBridge, Kinesis, KMS, and CloudWatch Logs reporting after its SDK integration test:
./gradlew -p examples/services verifyServices -PemulatorReport --configuration-cache
Open examples/services/build/reports/aws-emulator/default/managed/reportIntegrationEmulator/index.html. Run the same command again to check configuration-cache reuse. Add -PfailExample=true to capture the managed instance after a deliberate test failure and before cleanup.
Task Configuration
io.github.gregwhitaker.awsemulator.emulator.ReportAwsEmulatorTask supports:
| Property | Default | Purpose |
|---|---|---|
|
|
Select a named runtime; CLI |
|
|
Select lifecycle; CLI |
|
|
Directory containing |
|
|
Fail after writing incomplete reports; CLI |
|
|
Deadline for each SDK operation, including retries. |
Reports always query live state. Up-to-date skipping and build-cache reuse are disabled; configuration-cache reuse and Isolated Projects are supported.