diff --git a/Justfile b/Justfile index 110cd74b..f299973e 100644 --- a/Justfile +++ b/Justfile @@ -67,37 +67,162 @@ docs-serve: docs-watch: cd docs && mdbook serve -# CI Docker commands - automatically handle user mapping to prevent permission issues -ci-local: - docker build \ - --build-arg USER_ID=$(id -u) \ - --build-arg GROUP_ID=$(id -g) \ - -f Dockerfile.ci \ - --target ci-test \ - -t wassette-ci-local . - docker run --rm \ - -v $(PWD):/workspace \ - -w /workspace \ - -e GITHUB_TOKEN \ - wassette-ci-local just ci-build-test - -ci-build-test: - just build-test-components - cargo build --workspace - cargo test --workspace -- --nocapture - cargo test --doc --workspace -- --nocapture - -ci-build-test-ghcr: - just build-test-components - cargo build --workspace - cargo test --workspace -- --nocapture --include-ignored - cargo test --doc --workspace -- --nocapture - -ci-cache-info: - docker system df - docker images wassette-ci-* - -ci-clean: - docker rmi $(docker images -q wassette-ci-* 2>/dev/null) 2>/dev/null || true - docker builder prune -f - +# Development Environment Commands + +# Show available development commands +dev-help: + @echo "๐Ÿš€ Wassette Development Commands" + @echo "" + @echo "๐Ÿ“‹ Setup:" + @echo " just dev-check - Check development prerequisites" + @echo " just dev-check-ci - Check CI testing prerequisites (optional)" + @echo " just rust-setup - Set up Rust development environment" + @echo " just act-install - Install act tool for local CI" + @echo "" + @echo "๐Ÿงช Local CI Testing (matches GitHub exactly):" + @echo " just act-lint - Run linting checks" + @echo " just act-build - Run build and tests" + @echo " just act-security - Run security audits" + @echo " just act-rust-all - Run all Rust workflow jobs" + @echo "" + @echo "โšก Quick Development:" + @echo " just test - Run core tests (fast)" + @echo " just build - Build project" + @echo " just clean - Clean build artifacts" + @echo "" + @echo "๐Ÿ”ง Utilities:" + @echo " just act-clean - Clean up act containers" + @echo " just dev-help - Show this help" + +# Check if development prerequisites are installed +dev-check: + @echo "๐Ÿ” Checking development prerequisites..." + @command -v cargo >/dev/null 2>&1 || (echo "โŒ Rust/Cargo not installed. Run: just rust-setup" && exit 1) + @rustup target list --installed | grep -q wasm32-wasip2 || (echo "โŒ wasm32-wasip2 target not installed. Run: rustup target add wasm32-wasip2" && exit 1) + @echo "โœ… All prerequisites are installed!" + +# Check if CI testing prerequisites are installed (optional) +dev-check-ci: + @echo "๐Ÿ” Checking CI testing prerequisites..." + @command -v act >/dev/null 2>&1 || (echo "โŒ act not installed. Run: just act-install" && exit 1) + @command -v docker >/dev/null 2>&1 || (echo "โŒ Docker not installed. Please install Docker: https://docs.docker.com/get-docker/" && exit 1) + @echo "โœ… CI testing prerequisites are installed!" + +# Set up Rust development environment +rust-setup: + @echo "๐Ÿฆ€ Setting up Rust development environment..." + @echo "Checking nightly toolchain..." + @rustup toolchain list | grep -q nightly || rustup toolchain install nightly --component rustfmt + @echo "Checking wasm32-wasip2 target..." + @rustup target list --installed | grep -q wasm32-wasip2 || rustup target add wasm32-wasip2 + @echo "Checking cargo tools..." + @command -v cargo-machete >/dev/null 2>&1 || cargo install cargo-machete + @command -v cargo-audit >/dev/null 2>&1 || cargo install cargo-audit + @command -v cargo-deny >/dev/null 2>&1 || cargo install cargo-deny + @command -v typos >/dev/null 2>&1 || cargo install typos-cli + @echo "โœ… Rust development environment ready!" + +# Act commands - run GitHub CI locally using act (github.com/nektos/act) +# Each command corresponds to a specific job in .github/workflows/rust.yml +# Uses --rm to automatically clean up containers after each run +# +# To test against your own fork: +# just act-lint-fork github.com/yourusername/wassette +# just act-build-fork github.com/yourusername/wassette + +# Install act tool for running GitHub Actions locally +act-install: + @echo "Installing act (GitHub Actions runner)..." + @echo "Note: For security, the install script will be downloaded for your review before running with sudo." + tmpfile=$(mktemp /tmp/act-install.XXXXXX.sh) && \ + curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh -o "$tmpfile" && \ + echo "Downloaded install script to $tmpfile" && \ + echo "SHA256 checksum:" && sha256sum "$tmpfile" && \ + echo "Please review the script before running:" && \ + echo " less $tmpfile" && \ + echo "To install, run:" && \ + echo " sudo bash $tmpfile" + +act-license-headers: + act -W ./.github/workflows/rust.yml -j license-headers --rm + +act-lint: + act -W ./.github/workflows/rust.yml -j lint --rm + +act-build: + act -W ./.github/workflows/rust.yml -j build --rm + +act-deps: + act -W ./.github/workflows/rust.yml -j deps --rm + +act-security: + act -W ./.github/workflows/rust.yml -j security --rm + +act-coverage: + act -W ./.github/workflows/rust.yml -j coverage --rm + +act-spelling: + act -W ./.github/workflows/rust.yml -j spelling --rm + +act-linkChecker: + act -W ./.github/workflows/rust.yml -j linkChecker --rm + +# Run examples workflow +act-examples: + act -W ./.github/workflows/examples.yml --rm + +# Run all rust workflow jobs +act-rust-all: + act -W ./.github/workflows/rust.yml --rm + +# Run all workflows +act-all: + act -W ./.github/workflows/rust.yml --rm + act -W ./.github/workflows/examples.yml --rm + +# Fork-specific commands for testing custom repositories +act-license-headers-fork repo: + act -W ./.github/workflows/rust.yml -j license-headers --rm --env GITHUB_REPOSITORY={{repo}} + +act-lint-fork repo: + act -W ./.github/workflows/rust.yml -j lint --rm --env GITHUB_REPOSITORY={{repo}} + +act-build-fork repo: + act -W ./.github/workflows/rust.yml -j build --rm --env GITHUB_REPOSITORY={{repo}} + +act-deps-fork repo: + act -W ./.github/workflows/rust.yml -j deps --rm --env GITHUB_REPOSITORY={{repo}} + +act-security-fork repo: + act -W ./.github/workflows/rust.yml -j security --rm --env GITHUB_REPOSITORY={{repo}} + +act-coverage-fork repo: + act -W ./.github/workflows/rust.yml -j coverage --rm --env GITHUB_REPOSITORY={{repo}} + +act-spelling-fork repo: + act -W ./.github/workflows/rust.yml -j spelling --rm --env GITHUB_REPOSITORY={{repo}} + +act-linkChecker-fork repo: + act -W ./.github/workflows/rust.yml -j linkChecker --rm --env GITHUB_REPOSITORY={{repo}} + +# Run examples workflow against fork +act-examples-fork repo: + act -W ./.github/workflows/examples.yml --rm --env GITHUB_REPOSITORY={{repo}} + +# Run all rust workflow jobs against fork +act-rust-all-fork repo: + act -W ./.github/workflows/rust.yml --rm --env GITHUB_REPOSITORY={{repo}} + +# Run all workflows against fork +act-all-fork repo: + act -W ./.github/workflows/rust.yml --rm --env GITHUB_REPOSITORY={{repo}} + act -W ./.github/workflows/examples.yml --rm --env GITHUB_REPOSITORY={{repo}} + +# Clean up any stuck act containers +act-clean: + @echo "Current act containers:" + -docker ps --filter "name=act-" + @echo "Stopping and removing act containers..." + -docker stop $(docker ps -q --filter "name=act-") 2>/dev/null || true + -docker rm $(docker ps -aq --filter "name=act-") 2>/dev/null || true + @echo "Act containers cleaned up." diff --git a/README.md b/README.md index bd5b5aa3..25cf1167 100644 --- a/README.md +++ b/README.md @@ -380,6 +380,10 @@ You can join us via the `#wassette` channel on the [Microsoft Open Source Discor Please see [CONTRIBUTING.md][Contributing] for more information on how to contribute to this project. +## Development + +For local development and testing instructions, see [docs/development/developer-tests.md](docs/development/developer-tests.md). + ## License This project is licensed under the MIT License. diff --git a/docs/development/developer-tests.md b/docs/development/developer-tests.md new file mode 100644 index 00000000..9987af1e --- /dev/null +++ b/docs/development/developer-tests.md @@ -0,0 +1,259 @@ +# Developer Testing Guide + +This guide covers local development testing for Wassette, including CI parity testing and development environment setup. + +## Quick Start + +```bash +# Check prerequisites +just dev-check + +# Set up development environment (one-time setup) +just rust-setup + +# Install act for local CI testing (one-time setup) +just act-install + +# Run local CI tests (matches GitHub exactly) +just act-lint +just act-build +``` + +## Overview + +Wassette provides comprehensive local testing tools that ensure perfect parity between local development and GitHub CI. This prevents CI failures by catching issues before pushing code. + +### Key Benefits + +- **Perfect CI Parity**: Uses exact same GitHub Actions workflows locally +- **Zero Configuration Drift**: Always uses latest `.github/workflows/rust.yml` +- **Fork Testing**: Test against custom repositories and feature branches +- **Developer Experience**: Easy installation and clear commands +- **Automatic Cleanup**: Containers are automatically removed after use + +## Prerequisites + +### Required Tools + +- **Docker**: For running containerized CI environments +- **Rust/Cargo**: For building and testing Rust code +- **act**: For running GitHub Actions locally (can be installed via `just act-install`) + +### Rust Targets + +- `wasm32-wasip2`: Required for WebAssembly component builds + +## Development Environment Setup + +### One-Time Setup + +```bash +# Check what's installed +just dev-check + +# Set up complete Rust development environment +just rust-setup + +# Install act tool for local CI testing +just act-install +``` + +The `rust-setup` command installs: +- Nightly Rust toolchain with rustfmt +- `wasm32-wasip2` target for WebAssembly builds +- Additional tools: `cargo-machete`, `cargo-audit`, `cargo-deny`, `typos-cli` + +## Local CI Testing + +### Individual CI Jobs + +Run specific GitHub Actions jobs locally: + +```bash +# Linting (rustfmt + clippy) +just act-lint + +# Build and test +just act-build + +# Security audits +just act-security + +# Dependency checks +just act-deps + +# Coverage analysis +just act-coverage + +# Spell checking +just act-spelling + +# Link checking +just act-linkChecker + +# License header validation +just act-license-headers +``` + +### Workflow Testing + +```bash +# Run all Rust workflow jobs +just act-rust-all + +# Run examples workflow +just act-examples + +# Run all workflows +just act-all +``` + +## Fork and Branch Testing + +Test against custom repositories or feature branches: + +```bash +# Test against your fork +just act-lint-fork github.com/yourusername/wassette + +# Test against a specific branch (set up remote first) +git remote add feature-branch https://github.com/username/wassette +just act-build-fork github.com/username/wassette +``` + +### Available Fork Commands + +All CI jobs have corresponding fork variants: + +- `act-lint-fork repo` +- `act-build-fork repo` +- `act-security-fork repo` +- `act-deps-fork repo` +- `act-coverage-fork repo` +- `act-spelling-fork repo` +- `act-linkChecker-fork repo` +- `act-license-headers-fork repo` +- `act-examples-fork repo` +- `act-rust-all-fork repo` +- `act-all-fork repo` + +## Quick Development Testing + +For rapid development iteration: + +```bash +# Fast local tests (no containers) +just test + +# Build project +just build + +# Clean build artifacts +just clean +``` + +These commands run faster than full CI simulation but may not catch all CI-specific issues. + +## Container Management + +### Automatic Cleanup + +All `act-*` commands use the `--rm` flag for automatic container cleanup. + +### Manual Cleanup + +```bash +# Clean up any stuck act containers +just act-clean + +# View current act containers +docker ps --filter "name=act-" +``` + +## Troubleshooting + +### Common Issues + +**act not found** +```bash +# Install act via justfile +just act-install + +# Or install manually +curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash +``` + +**Docker permission denied** +```bash +# Add user to docker group (requires logout/login) +sudo usermod -aG docker $USER +``` + +**wasm32-wasip2 target missing** +```bash +# Install WebAssembly target +rustup target add wasm32-wasip2 +``` + +**Containers not cleaning up** +```bash +# Force cleanup +just act-clean + +# Check Docker space usage +docker system df +``` + +### Performance Tips + +1. **Use individual job commands** (`just act-lint`) instead of full workflows for faster feedback +2. **Run `just test` first** for quick validation before CI simulation +3. **Use fork commands** to test against feature branches without switching locally + +## Integration with IDE + +Most IDEs can run Justfile commands directly: + +- **VS Code**: Use the "Just" extension +- **IntelliJ/CLion**: Use the "Just" plugin +- **Command Line**: `just dev-help` for available commands + +## CI Workflow Mapping + +| Justfile Command | GitHub Actions Job | Purpose | +|------------------|-------------------|---------| +| `act-lint` | `lint` | Code formatting and linting | +| `act-build` | `build` | Build and test execution | +| `act-security` | `security` | Security vulnerability scans | +| `act-deps` | `deps` | Dependency analysis | +| `act-coverage` | `coverage` | Test coverage reporting | +| `act-spelling` | `spelling` | Spell checking | +| `act-linkChecker` | `linkChecker` | Documentation link validation | +| `act-license-headers` | `license-headers` | License header compliance | + +## Development Workflow + +### Recommended Flow + +1. **Start with quick tests**: `just test` +2. **Run relevant CI job**: `just act-lint` or `just act-build` +3. **Before pushing**: `just act-rust-all` +4. **For documentation changes**: `just act-spelling && just act-linkChecker` + +### Feature Branch Workflow + +```bash +# Create feature branch +git checkout -b feature/new-feature + +# Develop and test locally +just test + +# Test against your fork before creating PR +just act-build-fork github.com/yourusername/wassette + +# Final validation +just act-rust-all +``` + +This ensures your changes work correctly before submitting a pull request. \ No newline at end of file