Hands-on demo – Testing an Action in GitHub

Hands-on demo – Testing an Action in GitHub

Below is a step-by-step demo to test a custom GitHub Action. We'll create a local test workflow to validate the action's functionality.

Prerequisites

• A GitHub repository with a custom action defined (e.g., JavaScript/TypeScript or Docker-based).

• Basic knowledge of GitHub Actions YAML syntax.

Step 1: Define Your Action

1. Example: action.yml

A simple JavaScript-based GitHub Action that echoes an input value.

xxxxxxxxxx
9
1
name: "Echo Input Action"
2
description: "A simple action to echo an input"
3
inputs:
4
  message:
5
    description: "The message to echo"
6
    required: true
7
runs:
8
  using: "node16"
9
  main: "index.js"

2. Example: index.js

The Node.js script for the action.

xxxxxxxxxx
7
1
const core = require("@actions/core");
2
try {
3
  const message = core.getInput("message");
4
  console.log("Message: " . $message);
5
} catch (error) {
6
  core.setFailed(error.message);
7
}

Step 2: Create a Test Workflow

Define a separate GitHub workflow to test the action locally in your repository.

File:

.github/workflows/test-action.yml

xxxxxxxxxx
13
1
name: Test Echo Action
2
on:
3
  workflow_dispatch: # Allows manual triggering for testing
4
jobs:
5
  test-action:
6
    runs-on: ubuntu-latest
7
    steps:
8
     - name: Checkout Repository
9
        uses: actions/checkout@v3
10
     - name: Run the Action
11
        uses: ./ # Reference the action from the current repo
12
        with:
13
          message: "Hello from the test!"

Step 3: Trigger the Test Workflow

1. Commit and push the workflow file:

   xxxxxxxxxx
   3
   1
   git add .
   2
   git commit -m "Add test workflow"
   3
   git push origin main
   

2. Navigate to the Actions tab in your GitHub repository.

3. Select the "Test Echo Action" workflow.

4. Click Run workflow (manual trigger via workflow_dispatch).

Step 4: Analyze Console Output

1. After the workflow runs, click on the "test-action" job.

2. Look at the logs for the "Run the Action" step.

3. Example Output:

   xxxxxxxxxx
   2
   1
   Run ./ 
   2
   Message: Hello from the test!
   

Step 5: Add Debugging (Optional)

Enhance logging for more detailed output:

• Enable ACTIONS_STEP_DEBUG:

  xxxxxxxxxx
  2
  1
  env:
  2
  ACTIONS_STEP_DEBUG: true
  

• Add additional logs to your code:

  xxxxxxxxxx
  1
  1
  console.log("Debug: Starting action execution...");
  

Step 6: Automated Tests with Matrix Strategy

For comprehensive testing, include a matrix to validate across multiple configurations.

Example:

xxxxxxxxxx
13
1
jobs:
2
  test-action:
3
    runs-on: ubuntu-latest
4
    strategy:
5
      matrix:
6
        message: ["Test 1", "Test 2", "Test 3"]
7
    steps:
8
     - name: Checkout Repository
9
        uses: actions/checkout@v3
10
     - name: Run the Action
11
        uses: ./
12
        with:
13
          message: ${{ matrix.message }}

Output:

xxxxxxxxxx
3
1
Message: Test 1
2
Message: Test 2
3
Message: Test 3

Step 7: Testing Edge Cases

Update your test workflow to include invalid inputs:

xxxxxxxxxx
4
1
- name: Test Missing Input
2
  uses: ./
3
  with:
4
    message: "" # Intentionally empty input

Observe whether the action fails gracefully with a clear error message.

Step 8: Local Testing with Act

For faster testing, use the Act tool:

1. Install Act:

   xxxxxxxxxx
   1
   1
   brew install act
   

2. Run the workflow locally:

   xxxxxxxxxx
   1
   1
   act -j test-action
   

3. Debug and iterate on your action without triggering GitHub workflows.

Summary

This demo demonstrates how to define, test, and debug a GitHub Action effectively.