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"
  ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO:
    description: "The maximum number of tests ALKiln will generate for every Scenario that can generate tests."
    required: false
    # Default will be internal to avoid duplication of data

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_REPORT_LOG_FILE:
    description: 'An empty string ("") or the path to report_log.txt. Remember to check for the existence of the file before using it.'
    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_REPORT_LOG_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 }}
        ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO: ${{ inputs.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO }}
      shell: bash
      run: |
        log="💡 ALK0023 INFO: Set environment variables and create artifacts folder"

        # 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
        timestamp="$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)"
        artifact_folder="alkiln-${timestamp}UTC"
        debug_path="${artifact_folder}/debug_log.txt"
        mkdir -p "$artifact_folder"
        echo "$log" >> "$debug_path"

        # Action-specific vars
        echo "ARTIFACT_FOLDER=$artifact_folder" >> $GITHUB_ENV
        echo "DEBUG_PATH=$debug_path" >> $GITHUB_ENV

        # Required for all tests
        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 "ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO=$ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO" >> $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: |
        log="💡 ALK0024 INFO: Confirm environment variables"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        vars_log='\nALKiln version is ${{ env.ALKILN_VERSION }}\nRepo is "${{ env.REPO_URL }}"\nBranch ref is "${{ env.BRANCH_PATH }}"\nCustom MAX_SECONDS_FOR_SETUP is "${{ env.MAX_SECONDS_FOR_SETUP }}"\nCustom SERVER_RELOAD_TIMEOUT_SECONDS is "${{ env.SERVER_RELOAD_TIMEOUT_SECONDS }}"\nCustom ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO is "${{ env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO }}"\n'
        echo -e "$vars_log" >> "${{ env.DEBUG_PATH }}" && echo -e "$vars_log"

    # Install ALKiln during GitHub workflow
    - name: "💡 ALK0025 INFO: Set up node"
      uses: actions/setup-node@v5
      with:
        node-version: "24.x"
        package-manager-cache: false
    - name: "💡 ALK0026 INFO: Install ALKiln directly from npm"
      shell: bash
      run: |
        log="💡 ALK0026 INFO: Install ALKiln directly from npm"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        npm install -g "@suffolklitlab/alkiln@$ALKILN_VERSION"

    # Files prep
    - shell: bash
      env:
        ARTIFACT_FOLDER: ${{ env.ARTIFACT_FOLDER }}
      run: |
        log="💡 ALK0275 INFO: Prepare repository test files"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        alkiln-artifacts --path="${{ env.ARTIFACT_FOLDER }}"
        alkiln-validate
        alkiln-generate

    # Install package 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: |
        log="💡 ALK0027 INFO: Create a Project and install the package from GitHub"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        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"
        long_log="\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"
        echo -e "$long_log" >> "${{ env.DEBUG_PATH }}" && echo -e "$long_log"

    # Server installation
    - name: "💡 ALK0029 INFO: Try to install the GitHub package onto the GitHub sandbox server"
      if: ${{ inputs.INSTALL_METHOD == 'server' }}
      shell: bash
      run: |
        log="💡 ALK0029 INFO: Install the GitHub package onto the server"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        alkiln-server-install
    - name: "🤕 ALK0030 ERROR: Unable to install the package on the GitHub sandbox server"
      if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
      shell: bash
      run: |
        log="\n\n―――\n🤕 ALK0030 ERROR: Unable to install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
        echo -e "$log" >> "${{ env.DEBUG_PATH }}" && echo -e "$log"

    # 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: |
        log="💡 ALK0031 INFO: Run tests"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        alkiln-run "$ALKILN_TAG_EXPRESSION"
    
    # on playground, delete project
    - name: "💡 ALK0032 INFO: Delete the Project from the Playground"
      if: ${{ always() && inputs.INSTALL_METHOD == 'playground' }}
      shell: bash
      run: |
        log="💡 ALK0032 INFO: Delete the Project from the Playground"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
        alkiln-takedown
    
    # 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_FOLDER }}
        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_FOLDER }}

    - name: "💡 ALK0184 INFO: Prepare ALKiln output file paths"
      if: ${{ always() }}
      id: alkiln_outputs
      shell: bash
      run: |
        log="💡 ALK0184 INFO: Prepare ALKiln output file paths"
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo "$log"

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

        log_folder="Test results artifacts folder is $FOLDER"
        echo -e "\n$log_folder" >> "${{ env.DEBUG_PATH }}" && echo "$log_folder"

        if [[ "$FOLDER" = "" ]]; then
          log_missing="Artifacts folder is missing. The path is an empty string: '$FOLDER'"
          echo -e "\n$log_missing" >> "${{ env.DEBUG_PATH }}" && echo "$log_missing"

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

          if [ -f "$REPORT_PATH" ]; then
            echo -e "\n$REPORT_PATH exists" >> "${{ env.DEBUG_PATH }}" && echo "$REPORT_PATH exists"
          else
            echo -e "\n$REPORT_PATH is missing" >> "${{ env.DEBUG_PATH }}" && echo "$REPORT_PATH is missing"
            REPORT_PATH=""
          fi

          if [ -f "$REPORT_LOG_PATH" ]; then
            echo -e "\n$REPORT_LOG_PATH exists" >> "${{ env.DEBUG_PATH }}" && echo "$REPORT_LOG_PATH exists"
          else
            echo -e "\n$REPORT_LOG_PATH is missing" >> "${{ env.DEBUG_PATH }}" && echo "$REPORT_LOG_PATH is missing"
            REPORT_LOG_PATH=""
          fi

          if [ -f "$UNEXPECTED_RESULTS_PATH" ]; then
            echo -e "\n$UNEXPECTED_RESULTS_PATH exists" >> "${{ env.DEBUG_PATH }}" && echo "$UNEXPECTED_RESULTS_PATH exists"
          else
            echo -e "\n$UNEXPECTED_RESULTS_PATH is missing" >> "${{ env.DEBUG_PATH }}" && echo "$UNEXPECTED_RESULTS_PATH is missing"
            UNEXPECTED_RESULTS_PATH=""
          fi

          if [ -f "$DEBUG_LOG_PATH" ]; then
            echo -e "\n$DEBUG_LOG_PATH exists" >> "${{ env.DEBUG_PATH }}" && echo "$DEBUG_LOG_PATH exists"
          else
            echo -e "\n$DEBUG_LOG_PATH is missing" >> "${{ env.DEBUG_PATH }}" && 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_REPORT_LOG_FILE=$REPORT_LOG_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: |
        log="💡 ALK0034 INFO: ALkiln finished running tests. See above for more details."
        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo "$log"