Local Testing

WorkflowKt supports running workflows locally without GitHub Actions.

Setup

1. Create a Properties File

Create workflowkt.properties in your project root:

GITHUB_EVENT_PATH=core/src/test/resources/sample_issue_action.json
CUSTOM_PARAM=Hello World!

2. Prepare an Event Payload

Create a JSON file matching the GitHub event format. For example, sample_push_action.json:

{
  "ref": "refs/heads/main",
  "before": "4a71370caed771fe88c3c86c8eb93d10645a3a8d",
  "after": "a4fc963f44cf5101ca28ecc2fc7b039eb75f394a",
  "compare": "https://github.com/user/repo/compare/4a71370...a4fc963",
  "created": false,
  "deleted": false,
  "forced": false,
  "commits": [
    {
      "id": "a4fc963f44cf5101ca28ecc2fc7b039eb75f394a",
      "message": "feat: add new feature",
      "timestamp": "2025-12-23T21:38:14Z",
      "author": {
        "name": "Developer",
        "email": "dev@example.com"
      },
      "committer": {
        "name": "Developer",
        "email": "dev@example.com"
      },
      "distinct": true,
      "tree_id": "abc123",
      "url": "https://github.com/user/repo/commit/a4fc963"
    }
  ],
  "pusher": {
    "name": "developer",
    "email": "dev@example.com"
  },
  "sender": {
    "login": "developer",
    "id": 12345,
    "avatar_url": "https://avatars.githubusercontent.com/u/12345",
    "type": "User",
    "site_admin": false,
    "html_url": "https://github.com/developer"
  },
  "repository": {
    "id": 67890,
    "name": "my-repo",
    "full_name": "user/my-repo",
    "private": false,
    "owner": {
      "login": "user",
      "id": 12345,
      "avatar_url": "https://avatars.githubusercontent.com/u/12345",
      "type": "User",
      "site_admin": false,
      "html_url": "https://github.com/user"
    },
    "default_branch": "main",
    "html_url": "https://github.com/user/my-repo",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

3. Override the Properties File (Optional)

You can specify a custom properties file in your build script:

workflowkt {
    testEnvironmentFile = rootProject.file("my_test_env.properties")
}

Running Tests

Use the testWorkflowKt task:

./gradlew testWorkflowKt --key=<action_key>

Example

./gradlew testWorkflowKt --key=print_helloworld

Options

Option	Description
--key	The action key to test
--payload	Override the event payload file path

Payload Priority

1. --payload command-line option (highest priority)
2. GITHUB_EVENT_PATH from the properties file
3. Error if neither is provided

How Test Mode Works

1. The task loads workflowkt.properties (or the configured file)
2. A FakeEnvironment is created with those values
3. If GITHUB_EVENT_NAME is not in the properties, it's inferred from the action's context type
4. The event payload JSON is read from GITHUB_EVENT_PATH
5. The action runs with the fake environment and parsed context

Testing with JUnit

WorkflowKt also supports unit testing via CompositeActionContextFactory:

class ContextMapperTest {
    val factory = CompositeActionContextFactory()

    @Test
    fun testPushContext() {
        val json = javaClass.classLoader
            ?.getResource("sample_push_action.json")
            ?.readText()!!

        val context = factory.fromValues(
            eventName = "push",
            events = json
        )

        assertIs<PushContext>(context)
        assertEquals("refs/heads/main", context.ref)
        assertEquals(1, context.commits.size)
    }
}

This approach is useful for testing your context mapping logic without running the full Gradle task.