doc: clean up and expand docs

.github/functional_tests/lake_test_failure/action.yml

@@ -31,7 +31,7 @@ runs:
     - name: "run `lean-action` with `lake test`" 
       id: lean-action
       uses: ./
-      continue-on-error: true
+      continue-on-error: true # required so that the action does not fail the workflow
       with:
         test: true
         use-github-cache: false

.github/functional_tests/test_helpers/verify_action_outputs.sh

@@ -1,4 +1,9 @@
 #!/bin/bash
+
+# Expects the following environment variables to be set in the calling job step:
+# - OUTPUT_NAME: the name of the output to verify
+# - EXPECTED_VALUE: the expected value of the output
+# - ACTUAL_VALUE: the actual value of the output
 if [ "$ACTUAL_VALUE" != "$EXPECTED_VALUE" ]; then
     echo "Unexpected value for output $OUTPUT_NAME: $ACTUAL_VALUE (expected: $EXPECTED_VALUE)"
     exit 1

CONTRIBUTING.md

@@ -20,6 +20,12 @@ which runs when a PR proposes changes to critical files in the `lean-action` rep
 In the future, we will likely introduce additional entry points for tests,
 such as a more comprehensive test suite for release candidates.
 
+### Verifying `lean-action` outputs with `verify_action_outputs.sh`
+Functional tests use `verify_action_outputs.sh` (located in `.github/functional_tests/test_helpers`)
+along with a verification step in the test workflow to verify `lean-action` functions as expected in a given test scenario.
+
+See the `lake_test_failure` functional test for an example.
+
 ### Creating a new test
 When introducing new functionality to `lean-action`, consider creating a new functional test.
 Here are the steps to create a new test:
@@ -31,6 +37,7 @@ Here are the steps to create a new test:
         - For more information on the action syntax, see [creating a composite action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action).
 - Create a new job in `.github/workflows/functional_tests.yml` with a call to the newly created action.
 
+
 ### Running functional tests locally with `act`
 `lean-action` developers can leverage [act](https://github.com/nektos/act) to run tests locally.
 

README.md

@@ -136,7 +136,6 @@ steps:
   with:
     test: true
 
-
 - name: verify lean-action outputs
   env:
     TEST_STATUS: ${{ steps.lean-action.outputs.TEST_STATUS }}

action.yml

@@ -65,12 +65,12 @@ outputs:
   build-status:
     description: |
       The status of the `lake build`.
-      Allowed values: "SUCCESS" or "FAILURE".
+      Allowed values: "SUCCESS" | "FAILURE".
     value: ${{ steps.build.outputs.build-status }}
   test-status:
     description: |
       The status of the `lake test`.
-      Allowed values: "SUCCESS" or "FAILURE".
+      Allowed values: "SUCCESS" | "FAILURE".
     value: ${{ steps.test.outputs.test-status }}
 
 runs: