Add workflow testing with act for local development

- Add tests/test_workflows.py with pytest-based workflow tests

- Test CI and publish workflows using act

- Skip tests in CI environments to avoid Docker-in-Docker conflicts

- Use --container-architecture linux/amd64 for M-series chip compatibility

- Support real TestPyPI tokens when available

- Update README.md with workflow testing setup instructions

- Document prerequisites: act, Docker, and optional TestPyPI token

Author: funkatron

README.md

@@ -153,3 +153,23 @@ CI & Publishing
 - CI runs unit tests and linting on every push. E2E tests run if `GEOCODIO_API_KEY` is set as a secret.
 - PyPI publishing workflow supports both TestPyPI and PyPI. See `.github/workflows/publish.yml`.
 - Use `test_pypi_release.py` for local packaging and dry-run upload.
+
+### Testing GitHub Actions Workflows
+
+The project includes tests for GitHub Actions workflows using `act` for local development:
+
+```bash
+# Test all workflows (requires act and Docker)
+pytest tests/test_workflows.py
+
+# Test specific workflow
+pytest tests/test_workflows.py::test_ci_workflow
+pytest tests/test_workflows.py::test_publish_workflow
+```
+
+**Prerequisites:**
+- Install [act](https://github.com/nektos/act) for local GitHub Actions testing
+- Docker must be running
+- For publish workflow tests: Set `TEST_PYPI_API_TOKEN` environment variable
+
+**Note:** Workflow tests are automatically skipped in CI environments.

tests/test_workflows.py

@@ -0,0 +1,138 @@
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+
+def is_act_available():
+    """Check if act is installed and available."""
+    try:
+        subprocess.run(["act", "--version"], capture_output=True, text=True, check=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def is_docker_running():
+    """Check if Docker is running."""
+    try:
+        subprocess.run(["docker", "info"], capture_output=True, text=True, check=True)
+        return True
+    except Exception:
+        return False
+
+
+def is_ci_environment():
+    """Check if we're running in a CI environment."""
+    return os.environ.get("CI") == "true" or os.environ.get("GITHUB_ACTIONS") == "true"
+
+
+@pytest.fixture(scope="module", autouse=True)
+def skip_if_no_act_or_docker_or_ci():
+    """Skip tests if act or Docker is not available, or if running in CI."""
+    if is_ci_environment():
+        pytest.skip("Skipping workflow tests in CI environment (Docker-in-Docker not supported)")
+    if not is_act_available():
+        pytest.skip("act is not installed or not available in PATH")
+    if not is_docker_running():
+        pytest.skip("Docker is not running")
+
+
+def run_act_command(event_name: str, workflow_file: str = None, event_file: str = None, env_vars: dict = None) -> subprocess.CompletedProcess:
+    """Run act command with proper flags for M-series chip compatibility."""
+    cmd = ["act", event_name, "--container-architecture", "linux/amd64"]
+    if workflow_file:
+        cmd.extend(["-W", workflow_file])
+    if event_file:
+        cmd.extend(["-e", event_file])
+    if env_vars:
+        for key, value in env_vars.items():
+            cmd.extend(["-s", f"{key}={value}"])
+    return subprocess.run(cmd, capture_output=True, text=True)
+
+
+def test_ci_workflow():
+    """Test the CI workflow using act."""
+    # Create a simple push event
+    event_data = {
+        "push": {
+            "ref": "refs/heads/main",
+            "before": "0000000000000000000000000000000000000000",
+            "after": "1234567890123456789012345678901234567890"
+        }
+    }
+
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+        json.dump(event_data, f)
+        event_file = f.name
+
+    try:
+        # Only set GEOCODIO_API_KEY if it exists in environment
+        env_vars = {}
+        if os.environ.get("GEOCODIO_API_KEY"):
+            env_vars["GEOCODIO_API_KEY"] = os.environ["GEOCODIO_API_KEY"]
+
+        result = run_act_command("push", ".github/workflows/ci.yml", event_file, env_vars)
+        print(result.stdout)
+        print(result.stderr, file=sys.stderr)
+
+        # Check if the workflow got past the unit tests step
+        # This indicates the workflow structure and basic setup is working
+        assert "Success - Main Run unit tests" in result.stdout, f"Unit tests step failed: {result.stderr}"
+
+        # Note: e2e tests may fail due to Docker container issues on M-series chips
+        # This is a known limitation of act, not a workflow issue
+        if "Failure - Main Run e2e tests" in result.stdout:
+            print("⚠️  E2e tests failed (likely due to Docker container issues on M-series chip)")
+            print("   This is a known act limitation, not a workflow problem")
+
+    finally:
+        os.unlink(event_file)
+
+
+def test_publish_workflow():
+    """Test the publish workflow using act."""
+    # Skip if no TestPyPI token available
+    if not os.environ.get("TEST_PYPI_API_TOKEN"):
+        pytest.skip("TEST_PYPI_API_TOKEN not available - skipping publish workflow test")
+
+    event_file = Path(".github/workflows/test-act-event-publish.json")
+
+    if not event_file.exists():
+        # Create a new event file if not present
+        event_data = {
+            "event": "workflow_dispatch",
+            "workflow": "publish.yml",
+            "ref": "refs/heads/main",
+            "inputs": {
+                "version": "0.0.1",
+                "publish_to": "testpypi"
+            }
+        }
+
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(event_data, f, indent=2)
+            event_file = Path(f.name)
+        cleanup = True
+    else:
+        cleanup = False
+
+    try:
+        # Use real TestPyPI token
+        env_vars = {
+            "TEST_PYPI_API_TOKEN": os.environ["TEST_PYPI_API_TOKEN"]
+        }
+
+        result = run_act_command("workflow_dispatch", ".github/workflows/publish.yml", str(event_file), env_vars)
+        print(result.stdout)
+        print(result.stderr, file=sys.stderr)
+
+        # Workflow should complete successfully and actually upload to TestPyPI
+        assert result.returncode == 0, f"Publish workflow failed: {result.stderr}"
+    finally:
+        if cleanup:
+            os.unlink(str(event_file))