Skip to content

[plan] Document local testing workflows without GitHub Actions #8059

@github-actions

Description

@github-actions

Objective

Create comprehensive documentation for testing workflows locally without pushing to GitHub Actions, reducing feedback loop from minutes to seconds.

Context

Currently only 7 documentation references exist for local testing. Developers may need to push to GitHub Actions to test workflows, creating a slow feedback loop (2-5 minutes vs <1 second locally). The repository has 42 mock files suggesting testing infrastructure exists, but usage is not well documented.

Approach

  1. Create docs/guides/local-testing.md guide
  2. Document --no-emit flag and validation-only mode
  3. Explain --watch mode for rapid iteration
  4. Show how to test MCP server configurations locally
  5. Document mock/stub usage for GitHub API calls (leverage 42 existing mock files)
  6. Demonstrate testing workflow fragments independently
  7. Include troubleshooting section for common local testing issues
  8. Provide comparison table: local testing vs GitHub Actions testing
  9. Link guide from README.md under "Development" section

Guide Structure

# Local Workflow Testing Guide

## Overview
Test workflows in seconds, not minutes, without GitHub Actions.

## Quick Testing Methods

### 1. Validation-Only Mode
`gh-aw compile workflow.md --no-emit`

### 2. Watch Mode for Iteration  
`gh-aw compile workflow.md --watch`

### 3. Testing Workflow Fragments
[How to test shared fragments independently]

### 4. Mocking GitHub Context
[How to use the 42 mock files]

### 5. MCP Server Local Testing
[Local MCP server testing strategies]

## Comparison: Local vs GitHub Actions

| Aspect | Local Testing | GitHub Actions |
|--------|---------------|----------------|
| Feedback Time | <1 second | 2-5 minutes |
| Cost | Free | Consumes Actions minutes |
| Internet Required | No | Yes |
| Full Integration Test | No | Yes |

## When to Use Each Method
- Local: Syntax, validation, rapid iteration
- GitHub Actions: Integration testing, production deployment

Files to Create/Modify

  • Create: docs/guides/local-testing.md
  • Update: README.md (add link to guide)

Acceptance Criteria

  • Guide explains --no-emit flag and validation-only mode
  • Documents --watch mode for rapid iteration
  • Shows MCP server local configuration testing
  • Explains mock/stub usage for GitHub API calls
  • Demonstrates testing workflow fragments independently
  • Includes troubleshooting section for common issues
  • Provides comparison table: local vs GitHub Actions testing
  • Linked from README.md under "Development" section
  • Examples use actual mock files from repository

AI generated by Planning Assistant for #7631
Related to #8056

AI generated by Plan Command for discussion #7631

Metadata

Metadata

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions