The SDK has two categories of tests: unit tests that run without any credentials, and integration tests that call the live Apple Maps Server API and require a valid token.
Unit tests
Unit tests have no external dependencies and do not require APPLE_MAPS_TOKEN. Run them with:
Or using the Makefile shortcut:
Unit test classes follow the naming convention *Test (for example, GeocodeInputTest).
Integration tests
Integration tests call the real Apple Maps Server API. They are skipped automatically when APPLE_MAPS_TOKEN is not set, so they never block a CI build that has no credentials configured.
Integration test classes follow the naming convention *IT (for example, AppleMapsIT).
Setting up your token
Add your token
Open .env and set your token:APPLE_MAPS_TOKEN=your_token_here
.env-example file also shows the optional location bias variables you can configure:# Optional: default location bias for the CLI (format: <latitude>,<longitude>)
APPLE_MAPS_USER_LOCATION=37.7796095,-122.4016725
# Optional: natural-language location bias for the CLI (geocoded once per run)
APPLE_MAPS_USER_LOCATION_QUERY="San Francisco, CA"
Run the integration tests
Pass the token inline without a .env file:APPLE_MAPS_TOKEN="your-token" ./gradlew testDetail
APPLE_MAPS_TOKEN as a secret environment variable in your pipeline configuration. The testDetail task picks it up automatically. Running the full integration suite
./gradlew testDetail --tests com.williamcallahan.applemaps.AppleMapsIT
Running a single integration test
./gradlew testDetail --tests com.williamcallahan.applemaps.AppleMapsIT.geocodeHandlesPartialAndFullAddresses
geocodeHandlesPartialAndFullAddresses with the name of any test method in AppleMapsIT.
Naming conventions
| Convention | Example |
|---|
Unit test class ends with Test | GeocodeInputTest |
Integration test class ends with IT | AppleMapsIT |
Never commit a real APPLE_MAPS_TOKEN value to the repository. Use .env locally (which is listed in .gitignore) or CI secrets for pipeline runs.