test: add integration test infrastructure with .env support

Set up integration testing framework targeting ArcGIS Online:

Infrastructure:
- Add dotenvy for loading credentials from .env
- Create tests/common/ module with credential loading
- Add rate_limit() helper to be polite to AGOL API
- All integration tests marked with #[ignore] by default

Files:
- .env.example - Template for credentials
- tests/README.md - Documentation for running integration tests
- tests/common/mod.rs - Shared test utilities
- tests/integration_basic.rs - Basic connectivity tests

Credentials:
- Supports ARCGIS_API_KEY (read-only testing)
- Supports CLIENT_ID + CLIENT_SECRET (OAuth, future)
- .env already in .gitignore

Run integration tests with:
  cargo test --test integration_basic -- --ignored

Tests include 500ms rate limiting between API calls to be polite.

Author: crumplecup

.env.example

@@ -0,0 +1,12 @@
+# ArcGIS API Credentials
+# Copy this file to .env and fill in your credentials
+
+# Option 1: API Key (simplest for read-only access)
+ARCGIS_API_KEY=your_api_key_here
+
+# Option 2: OAuth Client Credentials (for full access)
+CLIENT_ID=your_client_id_here
+CLIENT_SECRET=your_client_secret_here
+
+# Optional: ArcGIS Online organization URL
+# ARCGIS_ORG_URL=https://yourorg.maps.arcgis.com

Cargo.lock

@@ -93,6 +93,7 @@ tokio-test = "0.4"
 mockito = "1"
 tracing-subscriber = "0.3"
 anyhow = "1"
+dotenvy = "0.15"
 
 [package.metadata.docs.rs]
 all-features = true

Cargo.toml

@@ -124,6 +124,37 @@ Run an example:
 cargo run --example query_features
 ```
 
+## Testing
+
+### Unit Tests
+
+Run unit tests (no credentials required):
+
+```bash
+cargo test
+```
+
+### Integration Tests
+
+Integration tests require ArcGIS credentials and hit live AGOL APIs.
+
+1. **Set up credentials**:
+   ```bash
+   cp .env.example .env
+   # Edit .env and add your ARCGIS_API_KEY or CLIENT_ID/CLIENT_SECRET
+   ```
+
+2. **Run integration tests**:
+   ```bash
+   # Run all integration tests (be patient, includes rate limiting)
+   cargo test --test integration_basic -- --ignored
+
+   # Run specific test
+   cargo test --test integration_basic test_public_feature_service_accessible -- --ignored
+   ```
+
+See [`tests/README.md`](tests/README.md) for more details.
+
 ## Authentication
 
 ### API Key

README.md

@@ -0,0 +1,66 @@
+# Integration Tests
+
+## Setup
+
+Integration tests require ArcGIS credentials. These tests are marked with `#[ignore]` to avoid hammering the API during normal test runs.
+
+### 1. Create `.env` file
+
+Copy the example file:
+
+```bash
+cp .env.example .env
+```
+
+### 2. Add your credentials
+
+Edit `.env` and add either:
+
+**Option A: API Key** (recommended for read-only testing):
+```bash
+ARCGIS_API_KEY=your_api_key_here
+```
+
+Get an API key from: https://developers.arcgis.com/dashboard
+
+**Option B: OAuth Credentials** (for full read/write testing):
+```bash
+CLIENT_ID=your_client_id_here
+CLIENT_SECRET=your_client_secret_here
+```
+
+### 3. Run integration tests
+
+Run all integration tests (hits live AGOL):
+
+```bash
+cargo test --test integration_basic -- --ignored
+```
+
+Run specific test:
+
+```bash
+cargo test --test integration_basic test_public_feature_service_accessible -- --ignored
+```
+
+## Rate Limiting
+
+Tests include `rate_limit()` calls to be polite to the ArcGIS Online API. Do not remove these delays.
+
+## Target Environment
+
+All integration tests target **ArcGIS Online (AGOL)**, not ArcGIS Enterprise.
+
+## Test Organization
+
+- `tests/common/` - Shared utilities, credential loading
+- `tests/integration_basic.rs` - Basic connectivity tests
+- `tests/integration_feature_service.rs` - Feature Service tests (TODO)
+- `tests/integration_geocoding.rs` - Geocoding tests (TODO)
+
+## Public Test Data
+
+Some tests use ESRI's public sample data:
+- World Cities Feature Service (read-only, no auth required)
+
+These tests verify basic API structure without requiring credentials.

tests/README.md

@@ -0,0 +1,72 @@
+//! Common utilities for integration tests.
+//!
+//! These tests target ArcGIS Online (AGOL) and require credentials
+//! set in a `.env` file at the repository root.
+
+use arcgis::{ArcGISClient, auth::ApiKeyAuth};
+use std::sync::OnceLock;
+
+/// Load environment variables from .env file.
+/// Only loads once, subsequent calls are no-ops.
+pub fn load_env() {
+    static INIT: OnceLock<()> = OnceLock::new();
+    INIT.get_or_init(|| {
+        dotenvy::dotenv().ok();
+    });
+}
+
+/// Get CLIENT_ID from environment.
+pub fn client_id() -> String {
+    load_env();
+    std::env::var("CLIENT_ID")
+        .expect("CLIENT_ID not found in environment. Add to .env file")
+}
+
+/// Get CLIENT_SECRET from environment.
+pub fn client_secret() -> String {
+    load_env();
+    std::env::var("CLIENT_SECRET")
+        .expect("CLIENT_SECRET not found in environment. Add to .env file")
+}
+
+/// Get an optional API key from environment.
+/// Some tests may use API key instead of OAuth.
+pub fn api_key() -> Option<String> {
+    load_env();
+    std::env::var("ARCGIS_API_KEY").ok()
+}
+
+/// Create a test client with API key authentication.
+///
+/// # Panics
+///
+/// Panics if ARCGIS_API_KEY is not set in environment.
+pub fn create_api_key_client() -> ArcGISClient {
+    let key = api_key().expect("ARCGIS_API_KEY not found in environment. Add to .env file");
+    let auth = ApiKeyAuth::new(key);
+    ArcGISClient::new(auth)
+}
+
+/// Public ArcGIS Online feature service for testing (read-only).
+/// This is ESRI's World Cities sample service.
+pub const SAMPLE_FEATURE_SERVICE: &str =
+    "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Cities/FeatureServer";
+
+/// Rate limiting helper to be polite to the API.
+/// Sleeps for a short duration between requests.
+pub async fn rate_limit() {
+    tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_env_loading() {
+        load_env();
+        // Just verify it doesn't panic
+        assert!(std::env::var("CLIENT_ID").is_ok() || std::env::var("ARCGIS_API_KEY").is_ok(),
+                "Either CLIENT_ID or ARCGIS_API_KEY should be set");
+    }
+}

tests/common/mod.rs

@@ -0,0 +1,62 @@
+//! Basic integration tests for ArcGIS SDK.
+//!
+//! These tests require credentials in a `.env` file.
+//! They are marked with `#[ignore]` by default to avoid hammering the API.
+//! Run with: `cargo test --test integration_basic -- --ignored`
+
+mod common;
+
+#[tokio::test]
+#[ignore = "Requires API key and hits live API"]
+async fn test_client_creation_with_api_key() {
+    let _client = common::create_api_key_client();
+    // Client creation should succeed without panicking
+    // Actual API calls will be tested in more specific tests
+}
+
+#[test]
+fn test_credentials_available() {
+    common::load_env();
+
+    // Either API key OR OAuth credentials should be available
+    let has_api_key = common::api_key().is_some();
+    let has_oauth = std::env::var("CLIENT_ID").is_ok() &&
+                    std::env::var("CLIENT_SECRET").is_ok();
+
+    assert!(has_api_key || has_oauth,
+            "Either ARCGIS_API_KEY or (CLIENT_ID + CLIENT_SECRET) must be set in .env");
+}
+
+#[tokio::test]
+#[ignore = "Hits live AGOL API - run sparingly"]
+async fn test_public_feature_service_accessible() {
+    // This test verifies we can reach a public AGOL service
+    // without authentication (read-only)
+
+    let client = reqwest::Client::new();
+    let url = format!("{}?f=json", common::SAMPLE_FEATURE_SERVICE);
+
+    common::rate_limit().await;
+
+    let response = client
+        .get(&url)
+        .send()
+        .await
+        .expect("Failed to reach AGOL sample service");
+
+    assert!(response.status().is_success(),
+            "Sample feature service should be accessible");
+
+    let json: serde_json::Value = response.json().await
+        .expect("Response should be valid JSON");
+
+    // Verify it's a feature service response
+    assert!(json.get("layers").is_some() || json.get("tables").is_some(),
+            "Response should contain layers or tables");
+}
+
+// TODO: Add more integration tests as we implement features:
+// - test_feature_query_with_auth
+// - test_feature_edit_operations
+// - test_oauth_flow
+// - test_rate_limiting