Merge pull request #6 from jonpugh/feature/wait-for

Add `wait-for` script

Author: jonpugh

.github/workflows/scripts.run-with-summary.yml

@@ -0,0 +1,68 @@
+# Test the scripts.
+name: Test Scripts
+on:
+  pull_request:
+    branches:
+    - main
+env:
+  # Allow running run-with-summary command.
+  PATH: ./src:./bin:./vendor/bin:/usr/local/bin:/usr/bin:/bin
+
+jobs:
+  
+  run-with-summary:
+    name: run-with-summary script
+    runs-on: ubuntu-latest
+    env:
+      SUCCESS: "Script run-with-summary succeeded! :white_check_mark:"
+      ERROR: "run-with-summary Failed! :x:"
+      SUMMARY: |
+        - Environment: https://pr${{ github.event.number }}.demo.site
+        - Pull Request: ${{github.event.pull_request.html_url }}
+    
+      # Show extra details
+      DEBUG: yes
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: run-with-summary success
+      env:
+        SUCCESS: "Directory List :white_check_mark:"
+      run: |
+        run-with-summary ls -la
+
+    - name: run-with-summary hide
+      env:
+        HIDE: true
+        SUCCESS: Processes
+        SUMMARY: This test should not show the process details table.
+      run: |
+        run-with-summary ps -aux
+
+    - name: run-with-summary failure
+      continue-on-error: true
+      env:
+        ERROR: "run-with-summary Failed on purpose! :x:"
+      run: |
+        echo $GITHUB_STEP_SUMMARY
+        run-with-summary ping w3.org -c5
+
+  wait-for:
+    name: wait-for script
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: wait-for failure
+      continue-on-error: true
+      env: 
+        TIMEOUT: 2
+      run: |
+        run-with-summary wait-for bad-command
+    
+    - name: wait-for success
+      continue-on-error: true
+      env: 
+        TIMEOUT: 5
+      run: |
+        run-with-summary wait-for sleep 2

.github/workflows/scripts.tests.yml

@@ -19,6 +19,9 @@ jobs:
     steps:
       - uses: jonpugh/goatscripts@v1
 ```
+## Scripts
+- `run-with-summary`: Runs a command and generates a markdown summary with output and execution details.
+- `wait-for`: Runs a command repeatedly until it passes.
 
 ## Run With Summary
 
@@ -70,3 +73,27 @@ jobs:
             Set SUMMARY env var to add *any* markdown **you want** to the report file.
 ```
 
+## wait-for
+
+runs a command until it passes or timeout is reached.
+
+### Use cases:
+
+- Docker containers that have to wait for a database server to start
+- Test scripts that have to wait for your project to initialize.
+- Better than "sleep": Sometimes you need to wait. Instead of sleeping a fixed number of seconds, run a command that will pass once the thing you need is ready.
+
+```
+wait-for mysql-ready
+wait-for curl https://deploy-url/ready
+```
+
+### Options
+
+```
+# SLEEP: Length of time to wait in-between running the command.
+# CHAR: The character to print after every command run.
+# OUTPUT: Set to 'all' to print all output, set to 'out' to print just stdOut, set to "err" to print just stdErr.
+# TIMEOUT: Default: 30. Exit with an error if process doesn't pass within this time.
+# SILENT: Set to 1 to not print any output except the timeout exceeded error. Useful when running from other scripts. See wait-mysql
+```

README.md

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# wait-for
+#
+# @author Jon Pugh
+# Created Jan 2020 for opendevshop: https://github.com/opendevshop/devshop/blob/1.x/scripts/wait-for
+#
+# Runs any command over and over again until it passes, hiding all output but printing a character every time it runs.
+#
+# Use Environment variables for options:
+#
+# SLEEP: Length of time to wait in-between running the command.
+# CHAR: The character to print after every command run.
+# OUTPUT: Set to 'all' to print all output, set to 'out' to print just stdOut, set to "err" to print just stdErr.
+# TIMEOUT: Default: 30. Exit with an error if process doesn't pass within this time.
+# SILENT: Set to 1 to not print any output except the timeout exceeded error. Useful when running from other scripts. See wait-mysql
+#
+
+# Document usage
+usage() {
+  cat <<<EOF
+Usage:
+  wait-for any-command any-arguments --any-options
+EOF
+}
+
+# Set Environment
+set -e
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+PATH="$DIR:$PATH"
+
+# Prepare arguments and options.
+COMMAND=$@
+
+# Environment Variables
+SLEEP=${SLEEP:-1}
+CHAR=${CHAR:-.}
+OUTPUT=${OUTPUT:-}
+TIMEOUT=${TIMEOUT:-30}
+SILENT=${SILENT:-""}
+
+# Check for required variables
+if [ -z "${COMMAND}" ]; then
+  usage
+  exit 1
+fi
+
+runCommand() {
+
+    # If $OUTPUT=out, hide errors.
+    if [ "${OUTPUT}" == "out" ]; then
+      $COMMAND 2> /dev/null
+
+    # If $OUTPUT=err, print only errors
+    elif [ "${OUTPUT}" == "err" ]; then
+      $COMMAND > /dev/null
+
+    # If $OUTPUT=all, just print
+    elif [ "${OUTPUT}" == "all" ]; then
+      $COMMAND
+
+    # Otherwise, hide output and errors
+    else
+      $COMMAND > /dev/null 2>&1
+    fi
+}
+
+if [ -z "${SILENT}" ]; then
+    echo "Running command until it succeeds: $COMMAND"
+fi
+
+while ! (runCommand)
+do
+    # Exit with an error if timeout is reached.
+    [ "$SECONDS" -gt "$TIMEOUT" ] && echo && echo "Timeout exceeded. Command failed for $SECONDS seconds." && exit 1
+
+    # Pause for $SLEEP seconds.
+    sleep $SLEEP
+
+    # Print $CHAR without a new line.
+    echo -n "$CHAR"
+done
+
+if [ -z "${SILENT}" ]; then
+  echo "Command completed after $SECONDS seconds."
+fi