Skip to content

act-local-testing.md

Latest commit

 

History

History
309 lines (229 loc) · 8.71 KB

act-local-testing.md

File metadata and controls

309 lines (229 loc) · 8.71 KB

Local GitHub Actions Testing with Act

This guide explains how to use act to run your GitHub Actions workflows locally, providing fast feedback and debugging capabilities for your CI/CD pipelines.

What is Act?

Act is a tool that allows you to run GitHub Actions locally using Docker. It reads your .github/workflows/ files and executes them in a local environment that mimics GitHub's runner environment.

Benefits

  • Fast Feedback: Test workflow changes without pushing to GitHub
  • Debugging: Identify issues before they reach CI
  • Resource Efficiency: No GitHub Actions minutes consumed
  • Local Development: Validate syntax and logic locally
  • Matrix Testing: Test all Python version combinations

Installation

macOS (using Homebrew)

brew install act

Other Platforms

See the act installation guide for your platform.

Prerequisites

  • Docker: Act requires Docker to be running
  • Docker Desktop: Recommended for macOS/Windows users

Starting Docker

# macOS
open -a Docker

# Linux
sudo systemctl start docker

Configuration

Apple Silicon (M1/M2/M3) Setup

If you're on Apple Silicon, you'll need to specify the container architecture:

# Create act configuration
mkdir -p "/Users/$USER/Library/Application Support/act"
echo "-P ubuntu-latest=catthehacker/ubuntu:act-latest" > "/Users/$USER/Library/Application Support/act/actrc"

Environment Variables

Act reads from your .env file. Ensure environment variable names use underscores (not hyphens):

# ✅ Correct format
fastwoe_token=pypi-...
xrisklab_token=pypi-...

# ❌ Incorrect format (act doesn't like hyphens)
fastwoe-token=pypi-...
xrisklab-token=pypi-...

Basic Usage

List Available Workflows

act --container-architecture linux/amd64 --list

Run All Jobs in a Workflow

# Run the CI workflow
act --container-architecture linux/amd64 -W .github/workflows/ci.yml

# Run the type checking workflow
act --container-architecture linux/amd64 -W .github/workflows/typecheck.yml

# Run compatibility tests
act --container-architecture linux/amd64 -W .github/workflows/compatibility.yml

Run Specific Jobs

# Run only the test job
act --container-architecture linux/amd64 -j test -W .github/workflows/ci.yml

# Run only the lint job
act --container-architecture linux/amd64 -j lint -W .github/workflows/ci.yml

# Run only the type-check job
act --container-architecture linux/amd64 -j type-check -W .github/workflows/ci.yml

Dry Run (Recommended for Testing)

# Validate workflow without executing
act --container-architecture linux/amd64 -W .github/workflows/ci.yml --dryrun

# Test specific job
act --container-architecture linux/amd64 -j lint -W .github/workflows/ci.yml --dryrun

FastWoe-Specific Examples

Testing New Features

When testing Kiro's new IV standard errors functionality:

# Test the enhanced type checking workflow
act --container-architecture linux/amd64 -W .github/workflows/typecheck.yml --dryrun

# Test CI type checking
act --container-architecture linux/amd64 -j type-check -W .github/workflows/ci.yml --dryrun

Matrix Testing

Test specific Python versions:

# Test Python 3.11 specifically
act --container-architecture linux/amd64 -j test -W .github/workflows/ci.yml --matrix python-version:3.11 --dryrun

# Test Python 3.12 specifically
act --container-architecture linux/amd64 -j test -W .github/workflows/ci.yml --matrix python-version:3.12 --dryrun

Event Simulation

Test different trigger events:

# Test pull request event
act --container-architecture linux/amd64 -W .github/workflows/ci.yml --event pull_request --dryrun

# Test push event (default)
act --container-architecture linux/amd64 -W .github/workflows/ci.yml --event push --dryrun

Workflow-Specific Commands

CI Workflow (ci.yml)

# Test all CI jobs
act --container-architecture linux/amd64 -W .github/workflows/ci.yml --dryrun

# Test only tests (Python 3.9-3.12 matrix)
act --container-architecture linux/amd64 -j test -W .github/workflows/ci.yml --dryrun

# Test only linting
act --container-architecture linux/amd64 -j lint -W .github/workflows/ci.yml --dryrun

# Test only type checking
act --container-architecture linux/amd64 -j type-check -W .github/workflows/ci.yml --dryrun

Type Checking Workflow (typecheck.yml)

# Test the dedicated type checking workflow
act --container-architecture linux/amd64 -W .github/workflows/typecheck.yml --dryrun

# This workflow includes:
# - Python 3.11 setup
# - uv installation
# - Dependencies installation
# - FastWoe & ty verification
# - CI checks (format, lint, typecheck)
# - Strict type checking

Compatibility Workflow (compatibility.yml)

# Test Python version compatibility
act --container-architecture linux/amd64 -W .github/workflows/compatibility.yml --dryrun

Release Workflow (release.yml)

# Test release process
act --container-architecture linux/amd64 -W .github/workflows/release.yml --dryrun

Advanced Usage

Verbose Output

act --container-architecture linux/amd64 -W .github/workflows/ci.yml -v --dryrun

Custom Environment Variables

act --container-architecture linux/amd64 -W .github/workflows/ci.yml --env CUSTOM_VAR=value --dryrun

Skip Jobs

# Skip specific jobs
act --container-architecture linux/amd64 -W .github/workflows/ci.yml --skip-job test --dryrun

Use Different Docker Image

# Use a different base image
act --container-architecture linux/amd64 -P ubuntu-latest=ubuntu:22.04 -W .github/workflows/ci.yml --dryrun

Troubleshooting

Common Issues

Docker Not Running

# Error: Cannot connect to the Docker daemon
# Solution: Start Docker Desktop
open -a Docker  # macOS

Apple Silicon Architecture Issues

# Error: Container architecture mismatch
# Solution: Always use --container-architecture linux/amd64
act --container-architecture linux/amd64 [other-options]

Environment Variable Issues

# Error: unexpected character "-" in variable name
# Solution: Use underscores instead of hyphens in .env file
fastwoe_token=...  # ✅ Correct
fastwoe-token=...   # ❌ Incorrect

Image Pull Issues

# Error: Failed to pull image
# Solution: Check Docker is running and has internet access
docker pull catthehacker/ubuntu:act-latest

Debugging Tips

  1. Start with dry runs: Always use --dryrun first to validate syntax
  2. Test individual jobs: Use -j job-name to isolate issues
  3. Check Docker: Ensure Docker is running and accessible
  4. Verify environment: Check your .env file format
  5. Use verbose mode: Add -v for detailed output

Integration with Development Workflow

Pre-commit Testing

# Test workflows before committing
act --container-architecture linux/amd64 -W .github/workflows/ci.yml --dryrun

# If dry run passes, commit your changes
git add .
git commit -m "Add new feature"
git push

Feature Development

# Test new workflow changes
act --container-architecture linux/amd64 -W .github/workflows/typecheck.yml --dryrun

# Test specific functionality
act --container-architecture linux/amd64 -j type-check -W .github/workflows/ci.yml --dryrun

Release Preparation

# Test release workflow
act --container-architecture linux/amd64 -W .github/workflows/release.yml --dryrun

# Test compatibility across Python versions
act --container-architecture linux/amd64 -W .github/workflows/compatibility.yml --dryrun

Best Practices

  1. Always use dry runs first: Validate syntax before execution
  2. Test individual jobs: Isolate issues by testing specific jobs
  3. Use consistent architecture flags: Always use --container-architecture linux/amd64 on Apple Silicon
  4. Keep environment clean: Ensure .env file uses proper naming conventions
  5. Test matrix combinations: Verify all Python version combinations work
  6. Validate new workflows: Test new workflow files before pushing

Resources

FastWoe Workflow Overview

Your project includes these workflows:

  • ci.yml: Main CI pipeline with tests, linting, and type checking
  • typecheck.yml: Dedicated type checking with ty integration
  • compatibility.yml: Python version compatibility testing
  • release.yml: Release automation and publishing

Each workflow can be tested locally using the commands above, providing fast feedback for your development process.