dotnet-geo-management/TESTING.md

Testing Guide

This document explains how to run tests for the Svrnty.GeoManagement library.

Test Types

The test suite includes integration tests that make real API calls to the Google Geocoding API.

Prerequisites

Before running tests, you need:

1. Google Maps API Key - Get one from Google Cloud Console

   • Enable the Geocoding API for your project
   • Create an API key credential
   • (Optional) Restrict the key to Geocoding API only

2. Configuration File - Set up your API key:

   cd Svrnty.GeoManagement.Tests
   cp appsettings.Example.json appsettings.Development.json
   

   Then edit appsettings.Development.json and add your API key:

   {
     "GoogleGeoManagement": {
       "ApiKey": "YOUR_ACTUAL_API_KEY_HERE",
       "Language": "en",
       "Region": "us"
     }
   }
   

   Note

   : The appsettings.Development.json file is in .gitignore and will not be committed to source control.

Running Tests

From the solution root:

dotnet test

From the test project directory:

cd Svrnty.GeoManagement.Tests
dotnet test

Important Notes

⚠️ API Costs & Limits:

• Tests make real API calls to Google
• Google provides a free tier but be aware of potential costs
• API has rate limits - don't run tests too frequently
• Each test run may use several API calls

🌐 Network Dependency:

• Tests require internet connection
• Tests may fail if Google API is down or rate limits are exceeded

Alternative: Environment Variables

Instead of using appsettings.Development.json, you can set the API key via environment variables:

export GoogleGeoManagement__ApiKey="your-api-key-here"
dotnet test

Note: Use double underscores (__) to represent nested configuration.

Test Coverage

Current integration tests cover:

• ✅ Forward geocoding (address → coordinates)
• ✅ Reverse geocoding (coordinates → address)
• ✅ Address normalization from object
• ✅ Address normalization from string
• ✅ Edge cases (invalid addresses, ocean coordinates)

Troubleshooting

Error: "Google API key not configured"

• Ensure appsettings.Development.json exists in the test project
• Verify the API key is correctly set in the configuration file
• Check that the file is being copied to the output directory

Error: "REQUEST_DENIED" or "OVER_QUERY_LIMIT"

• Verify the Geocoding API is enabled in your Google Cloud project
• Check your API key has permission to use the Geocoding API
• You may have exceeded your quota - wait before retrying

Tests are slow

• This is expected - tests make real network calls to Google's API
• Each test can take 1-2 seconds to complete