feat(ci): optional args input to run bashunit after install (#697)

Author: Chemaclass

.github/workflows/test-action.yml

@@ -46,3 +46,39 @@ jobs:
           test -n "$BASHUNIT_INSTALLED_VERSION"
           # add-to-path defaults to true, so "bashunit" resolves on PATH
           bashunit --version
+
+  run-via-args:
+    name: "Run via args input"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Write a passing and a failing sample test
+        run: |
+          mkdir -p sample_tests
+          printf 'function test_passes() { assert_same "1" "1"; }\n' > sample_tests/pass_test.sh
+          printf 'function test_fails() { assert_same "1" "2"; }\n' > sample_tests/fail_test.sh
+
+      - name: Run only the passing test via args (step should pass)
+        uses: ./
+        with:
+          directory: vendor/bashunit
+          args: sample_tests/pass_test.sh
+
+      - name: Run the failing test via args (expected to fail the step)
+        id: failing
+        continue-on-error: true
+        uses: ./
+        with:
+          directory: vendor/bashunit
+          add-to-path: 'false'
+          args: sample_tests/fail_test.sh
+
+      - name: Assert the failing run actually executed and failed
+        env:
+          OUTCOME: ${{ steps.failing.outcome }}
+        run: |
+          set -euo pipefail
+          # If args were ignored (install-only), the step would have succeeded.
+          test "$OUTCOME" = "failure"

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- GitHub Action `args` input: when set, runs `bashunit <args>` after installing, so a workflow can install and run the suite in a single step
+
 ## [0.38.0](https://github.com/TypedDevs/bashunit/compare/0.37.0...0.38.0) - 2026-06-07
 
 ### Added

action.yml

@@ -23,6 +23,10 @@ inputs:
     description: 'Verify the downloaded binary against the release sha256 checksum asset.'
     required: false
     default: 'true'
+  args:
+    description: 'If set, run "bashunit <args>" after installing (e.g. "tests/ --strict"). Empty = install only.'
+    required: false
+    default: ''
 
 outputs:
   path:
@@ -42,6 +46,7 @@ runs:
         BASHUNIT_DIRECTORY: ${{ inputs.directory }}
         BASHUNIT_ADD_TO_PATH: ${{ inputs.add-to-path }}
         BASHUNIT_VERIFY_CHECKSUM: ${{ inputs.verify-checksum }}
+        BASHUNIT_ARGS: ${{ inputs.args }}
         BASHUNIT_ACTION_PATH: ${{ github.action_path }}
       run: |
         set -euo pipefail
@@ -62,3 +67,10 @@ runs:
         if [ "$BASHUNIT_ADD_TO_PATH" = "true" ]; then
           echo "$target_dir" >> "$GITHUB_PATH"
         fi
+
+        # Optionally run the suite. Word-splitting of $BASHUNIT_ARGS is intentional
+        # so callers can pass multiple CLI arguments as a single string.
+        if [ -n "$BASHUNIT_ARGS" ]; then
+          # shellcheck disable=SC2086
+          "$target_dir/bashunit" $BASHUNIT_ARGS
+        fi

docs/installation.md

@@ -247,12 +247,21 @@ jobs:
       - run: bashunit tests
 ```
 
-**Inputs:** `version` (default `latest`), `directory` (default `lib`), `add-to-path` (default `true`), `verify-checksum` (default `true`).
-**Outputs:** `path` (binary path relative to the workspace), `version` (installed version).
-
-`verify-checksum` validates the downloaded binary against the release `checksum`
-asset (sha256) and fails the install on any mismatch. Set it to `false` only when
-pinning a release published before checksum assets existed.
+```yaml-vue [install + run]
+# .github/workflows/bashunit-tests.yml
+name: Tests
+on: [pull_request, push]
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Install and run the suite in a single step via the `args` input.
+      - uses: TypedDevs/bashunit@<commit-sha> # {{ pkg.version }}
+        with:
+          version: '{{ pkg.version }}'
+          args: tests/ --strict
+```
 
 ```yaml [via install.sh]
 # .github/workflows/bashunit-tests.yml
@@ -283,6 +292,13 @@ jobs:
 ```
 :::
 
+**Inputs:** `version` (default `latest`), `directory` (default `lib`), `add-to-path` (default `true`), `verify-checksum` (default `true`), `args` (default empty — when set, runs `bashunit <args>` after installing).
+**Outputs:** `path` (binary path relative to the workspace), `version` (installed version).
+
+`verify-checksum` validates the downloaded binary against the release `checksum`
+asset (sha256) and fails the install on any mismatch. Set it to `false` only when
+pinning a release published before checksum assets existed.
+
 ::: tip
 See bashunit's own pipeline for a real example: https://github.com/TypedDevs/bashunit/blob/main/.github/workflows/tests.yml
 :::