# 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](https://console.cloud.google.com/)
   - 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:

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

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

   ```json
   {
     "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:

```bash
dotnet test
```

From the test project directory:

```bash
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:

```bash
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