action.yml

name: "ALKiln: Automated docassemble tests"
description: "Automatically test any docassemble interview in a any branch on your GitHub repository whenever you commit or push. See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/setup/#types."

inputs:
  SERVER_URL:
    description: 'The url of your docassemble server. This should be in your GitHub SECRETS or the SECRETS of your org.'
    required: true
  DOCASSEMBLE_DEVELOPER_API_KEY:
    description: 'API key of the testing account with developer permissions on your docassemble server.'
    required: true
  # This is necessary to test pre-releases at the very least. It does seem
  # strange considering we're controlling everything through the action, but
  # that actually doesn't touch the npm version that's pulled in.
  ALKILN_VERSION:
    description: 'Version of ALKiln to get from npm.'
    required: false
    default: '^5.0.0'
  MAX_SECONDS_FOR_SETUP:
    description: "Amount of time to give the Project to upload your package's GitHub code."
    required: false
  SERVER_RELOAD_TIMEOUT_SECONDS:
    description: "Max amount of time to give the server to reload if it needs to"
    required: false
    # no default to let the custom Scenario timeouts create the reload timeout
  INSTALL_METHOD:
    description: "Default is 'playground'. Other option: 'server'. How to install the package onto the server."
    required: false
    default: "playground"
  ALKILN_TAG_EXPRESSION:
    description: "The tag expression to use to limit which tests to run. Default is no tag expression."
    required: false
  DOCASSEMBLECLI_VERSION:
    description: "The version of docassemblecli to install."
    required: false
    default: "0.0.17"

outputs:
  PATH_TO_ARTIFACTS:
    description: 'An empty string ("") or the path to the artifacts folder that contains the test run output. Remember to check for the existence of the folder before using it.'
    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_ARTIFACTS }}
  PATH_TO_REPORT_FILE:
    description: 'An empty string ("") or the path to report.txt. Remember to check for the existence of the file before using it.'
    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_REPORT_FILE }}
  PATH_TO_UNEXPECTED_RESULTS_FILE:
    description: 'An empty string ("") or the path to unexpected_results.txt. Remember to check for the existence of the file before using it.'
    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_UNEXPECTED_RESULTS_FILE }}
  PATH_TO_DEBUG_LOG_FILE:
    description: 'An empty string ("") or the path to debug_log.txt. Remember to check for the existence of the file before using it.'
    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_DEBUG_LOG_FILE }}

runs:
  using: "composite"
  steps:
    # Place the root directory in this branch
    - uses: actions/checkout@v4

    # Set environment variables
    - name: "💡 ALK0023 INFO: Set environment variables"
      # Safe input handling. Avoid evaluating in bash.
      env:
        BRANCH_PATH: ${{ github.ref }}
        BASE_URL: ${{ inputs.SERVER_URL }}
        DOCASSEMBLE_DEVELOPER_API_KEY: ${{ inputs.DOCASSEMBLE_DEVELOPER_API_KEY }}
        ALKILN_VERSION: ${{ inputs.ALKILN_VERSION }}
        MAX_SECONDS_FOR_SETUP: ${{ inputs.MAX_SECONDS_FOR_SETUP }}
        SERVER_RELOAD_TIMEOUT_SECONDS: ${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}
        DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
      shell: bash
      run: |
        # 💡 ALK0023 INFO: Set environment variables
        # Human-readable date/time: https://www.shell-tips.com/linux/how-to-format-date-and-time-in-linux-macos-and-bash/#how-to-format-a-date-in-bash
        echo "ARTIFACT_NAME=alkiln-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
        echo "REPO_URL=${{ github.server_url }}/${{ github.repository }}" >> $GITHUB_ENV
        echo "BRANCH_PATH=$BRANCH_PATH" >> $GITHUB_ENV
        # Workflow inputs
        echo "BASE_URL=$BASE_URL" >> $GITHUB_ENV
        echo "DOCASSEMBLE_DEVELOPER_API_KEY=$DOCASSEMBLE_DEVELOPER_API_KEY" >> $GITHUB_ENV
        echo "ALKILN_VERSION=$ALKILN_VERSION" >> $GITHUB_ENV
        echo "MAX_SECONDS_FOR_SETUP=$MAX_SECONDS_FOR_SETUP" >> $GITHUB_ENV
        echo "SERVER_RELOAD_TIMEOUT_SECONDS=$SERVER_RELOAD_TIMEOUT_SECONDS" >> $GITHUB_ENV
        echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
        # Hard-coded internal ALKiln vars
        echo "_ORIGIN=github" >> $GITHUB_ENV
    - name: "💡 ALK0024 INFO: Confirm environment variables"
      shell: bash
      run: |
        # 💡 ALK0024 INFO: Confirm environment variables
        echo -e "\nALKiln version is $ALKILN_VERSION\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nMAX_SECONDS_FOR_SETUP is $MAX_SECONDS_FOR_SETUP\nSERVER_RELOAD_TIMEOUT_SECONDS is $SERVER_RELOAD_TIMEOUT_SECONDS\n"

    # Install
    - name: "💡 ALK0025 INFO: Install node packages"
      uses: actions/setup-node@v4
      with:
        node-version: "18"
    - name: "💡 ALK0026 INFO: Install ALKiln directly from npm"
      shell: bash
      run: |
        # 💡 ALK0026 INFO: Install ALKiln directly from npm
        npm install -g "@suffolklitlab/alkiln@$ALKILN_VERSION"

    # Install on playground

    # Don't rely on the environment's version of python
    - uses: actions/setup-python@v5
      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
      with:
        python-version: '3.10'
    - name: "💡 ALK0027 INFO: Create a Project and install the package from GitHub"
      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
      shell: bash
      run: |
        # 💡 ALK0027 INFO: Create a Project and install the package from GitHub
        pip install "docassemblecli==$DOCASSEMBLECLI_VERSION"
        alkiln-setup
    - name: "😞 ALK0028 ERROR: Unable to create a Project"
      if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
      shell: bash
      run: |
        # 😞 ALK0028 ERROR: Unable to create a Project
        echo -e "\n\n====\n😞 ALK0028 ERROR: Unable to create a Project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"

    # Server installations - find folders and save session vars
    - name: "💡 ALK0029 INFO: Install the GitHub package onto the server"
      if: ${{ inputs.INSTALL_METHOD == 'server' }}
      shell: bash
      run: alkiln-server-install
    - name: "😞 ALK0030 ERROR: Unable to install the package"
      if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
      shell: bash
      run: |
        echo -e "\n\n====\n😞 ALK0030 ERROR: Unable to install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"

    # run tests
    - name: "💡 ALK0031 INFO: Run tests"
      if: ${{ success() }}
      env:
        ALKILN_TAG_EXPRESSION: ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
      shell: bash
      run: alkiln-run "$ALKILN_TAG_EXPRESSION"
    
    # on playground, delete project
    - name: "💡 ALK0032 INFO: Delete the Project from the Playground"
      if: ${{ always() && inputs.INSTALL_METHOD == 'playground' }}
      run: alkiln-takedown
      shell: bash
    
    # Upload artifacts that subscribers can download on the Actions summary page
    - name: "💡 ALK0033 INFO: Upload artifacts folder"
      if: ${{ always() }}
      uses: actions/upload-artifact@v4
      with:
        name: ${{ env.ARTIFACT_NAME }}
        path: ./alkiln-*

    # Download artifacts folder internally to create action output
    - name: "💡 ALK0183 INFO: Get uploaded artifacts folder"
      if: ${{ always() }}
      uses: actions/download-artifact@v4
      with:
        name: ${{ env.ARTIFACT_NAME }}

    - name: "💡 ALK0184 INFO: Prepare ALKiln output file paths"
      if: ${{ always() }}
      id: alkiln_outputs
      shell: bash
      run: |
        # 💡 ALK0184 INFO: Prepare ALKiln output file paths

        FOLDER=$(ls -d */ | grep -E '^alkiln-*' || true)

        echo "Test results artifacts folder is $FOLDER"

        if [[ "$FOLDER" = "" ]]; then
          echo "Artifacts folder is missing. The path is an empty string: '$FOLDER'"

        else
          REPORT_PATH="${FOLDER}report.txt"
          UNEXPECTED_RESULTS_PATH="${FOLDER}unexpected_results.txt"
          DEBUG_LOG_PATH="${FOLDER}debug_log.txt"

          if [ -f "$REPORT_PATH" ]; then
            echo "$REPORT_PATH exists"
          else
            echo "$REPORT_PATH is missing"
            REPORT_PATH=""
          fi

          if [ -f "$UNEXPECTED_RESULTS_PATH" ]; then
            echo "$UNEXPECTED_RESULTS_PATH exists"
          else
            echo "$UNEXPECTED_RESULTS_PATH is missing"
            UNEXPECTED_RESULTS_PATH=""
          fi

          if [ -f "$DEBUG_LOG_PATH" ]; then
            echo "$DEBUG_LOG_PATH exists"
          else
            echo "$DEBUG_LOG_PATH is missing"
            DEBUG_LOG_PATH=""
          fi

        fi

        echo "PATH_TO_ARTIFACTS=$FOLDER" >> "$GITHUB_OUTPUT"
        echo "PATH_TO_REPORT_FILE=$REPORT_PATH" >> "$GITHUB_OUTPUT"
        echo "PATH_TO_UNEXPECTED_RESULTS_FILE=$UNEXPECTED_RESULTS_PATH" >> "$GITHUB_OUTPUT"
        echo "PATH_TO_DEBUG_LOG_FILE=$DEBUG_LOG_PATH" >> "$GITHUB_OUTPUT"

    # Avoid creating output from text in files
    # Cannot properly create outputs with multi-line text. Collapses onto one line.

    - shell: bash
      if: ${{ always() }}
      run: |
        echo "💡 ALK0034 INFO: ALkiln finished running tests"