Add comprehensive local development and CI testing tools

[attackordie]

Fixes #278 - Add Local Development Testing Guide

Summary

This PR implements comprehensive local development and CI testing tools that provide perfect parity between local development and GitHub CI environments. This directly addresses issue #278 by providing developers with the tools needed to catch issues locally before pushing.

Problems Solved

• CI/Local Mismatch: Developers experience CI failures that don't occur locally
• No Local CI Testing: Missing ability to run exact GitHub Actions workflows locally
• Poor Developer Onboarding: No documented development workflow or prerequisites
• Configuration Drift: Manual maintenance of local testing commands vs CI workflows

Solution Overview

Implements act-based local CI testing system using GitHub workflows as single source of truth:

Key Features

• Perfect CI Parity: Run exact same GitHub Actions workflows locally via act
• Zero Configuration Drift: Always uses latest .github/workflows/rust.yml
• Fork Testing Support: Test against custom repositories and feature branches
• Individual Job Commands: Run specific CI jobs (act-lint, act-build, etc.)
• Automatic Cleanup: Containers removed automatically with --rm flags
• Easy Setup: One-command installation and environment verification

New Justfile Commands

Development Environment

• dev-help - Show all available development commands with usage
• dev-check - Verify development prerequisites are installed
• rust-setup - Set up complete Rust development environment
• act-install - Install act tool with user guidance

Local CI Testing (Perfect GitHub Parity)

• act-lint - Run linting checks (rustfmt + clippy)
• act-build - Run build and tests
• act-security - Run security audits
• act-deps - Run dependency checks
• act-coverage - Run coverage analysis
• act-spelling - Run spell checking
• act-linkChecker - Run link validation
• act-license-headers - Run license header validation
• act-rust-all - Run all Rust workflow jobs
• act-examples - Run examples workflow
• act-all - Run all workflows

Fork/Branch Testing

• act-lint-fork repo - Test linting against custom repository
• act-build-fork repo - Test build against custom repository
• All CI jobs have corresponding -fork variants

Container Management

• act-clean - Clean up any stuck act containers

Documentation Added

• docs/development/developer-tests.md - Comprehensive developer testing guide
• Updated README.md with development section and quick start

Usage Examples

Quick Setup (One-time)

# Check what's installed
just dev-check

# Set up development environment  
just rust-setup

# Install act for local CI testing
just act-install

Local CI Testing

# Run individual CI jobs (fast feedback)
just act-lint
just act-build

# Run all CI jobs (full validation)
just act-rust-all

Fork/Branch Testing

# Test against your fork before creating PR
just act-lint-fork github.com/yourusername/wassette

# Test against feature branch
just act-build-fork github.com/contributor/wassette

Benefits

For Contributors

• Catch Issues Early: Find CI failures locally before pushing
• Faster Development: Quick feedback with individual job commands
• Easy Onboarding: Clear setup instructions and prerequisites checking
• Flexible Testing: Test against forks and feature branches

For Maintainers

• Fewer Failed PRs: Contributors catch issues locally first
• Consistent Environment: All developers use same CI workflows
• Less Support Burden: Self-documenting development workflow
• Zero Maintenance: Uses existing GitHub workflow definitions

For Project

• Higher Code Quality: More thorough local testing
• Faster CI/CD: Fewer failed builds and re-runs
• Better Documentation: Comprehensive development guides
• Community Growth: Lower barrier to contribution

Implementation Details

act Integration

• Uses nektos/act to run GitHub Actions locally in Docker containers
• Each Justfile command maps directly to a GitHub workflow job
• Automatic container cleanup prevents resource accumulation
• Support for custom repositories via environment variables

Documentation Structure

• Detailed guide in docs/development/developer-tests.md
• Quick start section in main README.md
• Troubleshooting and performance tips included
• IDE integration guidance provided

Backward Compatibility

• All existing Justfile commands preserved
• New commands follow existing naming conventions
• No changes to CI workflows or project structure
• Optional adoption - existing workflow continues to work

Testing

This PR has been thoroughly tested:

• All new Justfile commands verified working
• act integration tested against multiple workflow jobs
• Fork testing validated with custom repository
• Documentation accuracy verified
• Prerequisites checking confirmed on clean environment

Future Enhancements

This foundation enables future improvements:

• Integration with IDE development workflows
• Automated testing in VS Code/IntelliJ
• Performance optimizations for faster feedback
• Custom workflow compositions for specific development scenarios

This PR directly solves issue #278 by providing developers with the exact tools requested: comprehensive local development testing that matches GitHub CI behavior.

[attackordie]

need to rebase first.

[cataggar]

I wish all my CI had this.

[attackordie]

I was so embarrassed with my failed CI testing creating more work for others.

[Copilot]

Pull Request Overview

This PR implements comprehensive local development and CI testing tools using act (GitHub Actions runner) to provide perfect parity between local development and GitHub CI environments. The implementation addresses issue #278 by enabling developers to run exact GitHub Actions workflows locally, catch CI failures before pushing, and test against forks and feature branches.

• Adds comprehensive local CI testing system using act with perfect GitHub Actions parity
• Implements development environment setup and prerequisites checking
• Provides extensive developer documentation and workflow guidance

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/development/developer-tests.md	Comprehensive developer testing guide with setup instructions, CI testing workflows, and troubleshooting
README.md	Added development section with quick start guide and local CI testing overview
Justfile	Major expansion with 30+ new commands for development environment setup, local CI testing, and fork testing

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[attackordie]

Thanks for the feedback! I've moved the Development section out of the README as suggested and replaced it with a link to the comprehensive developer testing guide.

This PR aims to improve developer experience by providing local CI testing tools that match GitHub Actions exactly. This should help catch issues before pushing, reduce CI failures, and save maintainers time on troubleshooting. The act integration lets developers run the same linting, security, and build checks locally that run in CI. Don't have 'act'? No worries there is an included command to install from inside this repo with just act-install.

[thomastaylor312]

I'm not sure I really like having a hard dep on act here. FWIW, I love the project and use it, but I'd rather make sure our CI steps just run just targets (like unit-test) that use the normal Rust/Wasm build toolchains so we can run the same just targets locally.

The one thing I do understand it does better is that it helps with building/testing the examples, but I don't know that it justifies running everything with act (plus installing/updating the local containers for use as the runners)

EDIT:

For clarity, I really don't think act should be our local runner for everything as it is slower (you're running in a container) and more resource intensive than doing things locally and forces everyone to use it if they want to use our make targets. It isn't like a dev container or nix devShell where it is optional

[thomastaylor312]

Marking as blocking so we can have the discussion about my comment above. Also left one comment

[thomastaylor312]

I'd like this to check and see if these things are installed first before updating. Otherwise it will update every day you run it (because it is installing nightly). I love having this target, but it should check

[attackordie]

@thomastaylor312 You're absolutely right on both points, and I completely agree that act should be
optional and not a hard dependency.

Making Act Truly Optional:
My intention was always to provide act as an additional testing method, not replace the existing workflow. I can modify the PR to:

1. Remove act from dev-check - the core development prerequisites should remain the same
2. Create a separate dev-check-ci command for those who want to use act
3. Have rust-setup check existing installations first.

The PR would then be 100% backwards compatible:

• Existing developers continue using just test + cargo clippy as always
• New developers can optionally install act for exact CI validation
• CI continues working identically

Regarding Native CI Targets:
I understand your preference for just targets that use native Rust/Wasm toolchains. The challenge is that GitHub CI uses specific container environments, dependency versions, and configurations that are difficult to perfectly replicate natively. But you're right that for daily development, native tools are faster and more efficient.

Would you prefer to make act completely optional or is there another solution?

[Mossaka]

Hey! I would prefer to keep a short "how to use act" page under docs/development explaining that this is a best-effort, and have links to nektos/acat docs. Avoid "perfect parity" language since in practice, we all know that it has meaninful gaps and we'd be setting false expectations.

Also, I am not a fan of introducing a bunch of just targets. I would also prefer to remove changes to the Justfile, and have one neutral entry point like just ci-local-act that runs act -W .github/workflows/rust.yml and no fork shortcuts.

So, I’d accept a slimmer PR that adds a docs-only page describing optional act usage and introduces at most one neutral just ci-local-act target (no job-level commands).

[attackordie]

Understand. I'll make it happen.

[attackordie]

Running local CI testing is now less restrictive and 'act' CI runs are optional. Added checks to the 'just dev-check' command so it's safe to run daily if desired.

Any requests, deletions or additions?