@suffolklitlab/alkiln 5.6.0 → 5.7.0

package/.github/workflows/github_server.yml

@@ -1,7 +1,9 @@
-name: GitHub server tests
+name: GitHub server installation
 
 on:
   push:
+  # Default opened, reopened, synchronize. "edited" is something else.
+  pull_request_target:
   workflow_dispatch:
     inputs:
       tags:
@@ -33,7 +35,9 @@ jobs:
       SECRET_FOR_MISSING_FIELD: secret for missing field
       
     steps:
-      # Place the root directory in this branch
+      #### Developer note: You probably don't need this
+      # Place the root directory in this branch to access
+      # relative paths to action files
       - uses: actions/checkout@v3
 
       - name: ALKiln - Start the isolated temporary docassemble server on GitHub
@@ -83,7 +87,5 @@ jobs:
           INSTALL_METHOD: "server"
           #### Developer note: Useful for temporarily shortening ALKiln tests
           #### to debug the docker install step
-          # ALKILN_TAG_EXPRESSION: @onetest
-      - run: echo "ALkiln finished running ALKiln tests"
-        shell: bash
+          # ALKILN_TAG_EXPRESSION: @a_tag_expression
 

package/.github/workflows/playground.yml

@@ -0,0 +1,56 @@
+name: Playground installation
+
+on:
+  push:
+  # Default: opened, reopened, synchronize. "edited" is not what we want.
+  pull_request_target:
+  workflow_dispatch:
+    inputs:
+      tags:
+        required: False
+        description: 'Optional. Use a "tag expression" specify which tagged tests to run (https://cucumber.io/docs/cucumber/api/#tag-expressions)'
+        default: ''
+
+jobs:
+
+  puppeteer-tests:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    env:
+      #### Developer note: Required
+      SERVER_URL: ${{ secrets.SERVER_URL }}
+      DOCASSEMBLE_DEVELOPER_API_KEY: ${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}
+      #### Developer note: you don't need any of these
+      # Specific to our repo's tests
+      PLAYGROUND_EMAIL: ${{ secrets.PLAYGROUND_EMAIL }}
+      PLAYGROUND_PASSWORD: ${{ secrets.PLAYGROUND_PASSWORD }}
+      PLAYGROUND_ID: ${{ secrets.PLAYGROUND_ID }}
+      USER1_EMAIL: ${{ secrets.USER1_EMAIL }}
+      USER1_PASSWORD: ${{ secrets.USER1_PASSWORD }}
+      SECRET_VAR1: secret-var1-value
+      SECRET_VAR2: secret-var2-value
+      SECRET_FOR_MISSING_FIELD: secret for missing field
+      # Internal
+      _ORIGIN: github
+
+    name: Run ALKiln tests
+    steps:
+      #### Developer note: You probably don't need this
+      # Place the root directory in this branch to access
+      # relative paths to action files
+      - uses: actions/checkout@v3
+
+      #### Developer note: you'll need to replace `.` with the path to
+      #### the repo and branch and leave off the trailing `/`
+      #### For example suffolkLITLab/ALKiln@v5
+      - uses: ./
+        with:
+          SERVER_URL: "${{ env.SERVER_URL }}"
+          DOCASSEMBLE_DEVELOPER_API_KEY: "${{ env.DOCASSEMBLE_DEVELOPER_API_KEY }}"
+          #### Developer note: Useful for temporarily shortening ALKiln tests
+          #### to debug the docker install step
+          # ALKILN_TAG_EXPRESSION: @a_tag_expression

package/.github/workflows/unit_tests.yml

@@ -0,0 +1,35 @@
+name: Unit tests
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+
+  unit-tests:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    name: Run unit tests
+    steps:
+      - name: Set name of artifact folder with date and UTC 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
+        run: |
+          echo "UNIT_TESTS_ARTIFACT_NAME=_alkiln-misc-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run unit
+      # Artifacts
+      - name: upload unit tests artifacts folder
+        uses: actions/upload-artifact@v3
+        # This will upload even if a previous step has failed
+        if: ${{ always() }}
+        with:
+          name: ${{ env.UNIT_TESTS_ARTIFACT_NAME }}
+          path: ./_alkiln-*

package/CHANGELOG.md

@@ -45,6 +45,18 @@ Format:
 
 <!-- ## [Unreleased] -->
 
+## [5.7.0] - 2023-11-14
+
+### Added
+- Allow tests to run when a PR is made by switching to docassemblecli's `dainstall` to upload packagese to the Playground. See [#760](https://github.com/SuffolkLITLab/ALKiln/issues/760).
+
+### Internal
+- Workflows:
+  - Split unit tests into their own file. They have to use `npm install` in our repo and we don't want to use that for Playground tests. It avoids trying to push all the node modules to the Playground which would otherwise cause error 413 "too large".
+  - Use our own action in the tests that install on the Playground, to avoid duplicating edits to the action - see [#822](https://github.com/SuffolkLITLab/ALKiln/issues/822).
+  - Rename files
+  - Also see [#822](https://github.com/SuffolkLITLab/ALKiln/issues/822)
+
 ## [5.6.0] - 2023-10-27
 
 ### Changed

package/action.yml

@@ -35,11 +35,15 @@ inputs:
 runs:
   using: "composite"
   steps:
+    # Place the root directory in this branch
+    - uses: actions/checkout@v3
+
     # Set environment variables
-    - name: "ALKiln: Set environment variables"
+    - name: "ALKiln setup 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
       run: |
+        # ALKiln setup info: Set environment variables
         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=${{ github.ref }}" >> $GITHUB_ENV
@@ -50,59 +54,75 @@ runs:
         echo "SERVER_RELOAD_TIMEOUT_SECONDS=${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}" >> $GITHUB_ENV
         echo "_ORIGIN=github" >> $GITHUB_ENV
       shell: bash
-    - name: "ALKiln: confirm info"
+    - name: "ALKiln setup info: confirm environment variables"
       run: |
+        # ALKiln setup 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"
       shell: bash
 
     # Install
-    - name: "ALKiln: Install node packages"
+    - name: "ALKiln setup info: Install node packages"
       uses: actions/setup-node@v3
       with:
         node-version: "18"
     - name: Install ALKiln directly from npm
       run: |
+        # ALKiln setup info: Install ALKiln directly from npm
         npm install -g @suffolklitlab/alkiln@$ALKILN_VERSION
       shell: bash
 
     # Install on playground
-    - name: "ALKiln: Create a Project and pull the package from GitHub"
+
+    # Don't rely on the environment's version of python
+    - uses: actions/setup-python@v4
+      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
+      with:
+        python-version: '3.10'
+    - name: "ALKiln: Create a Project and install the package from GitHub"
       if: ${{ inputs.INSTALL_METHOD == 'playground' }}
-      run: alkiln-setup
+      run: |
+        # ALKiln setup info: Create a Project and install the package from GitHub
+        pip3 install docassemblecli
+        alkiln-setup
       shell: bash
-    - run: echo -e "\n\n====\nALKiln could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
+    - name: "ALKiln setup ERROR"
+      run: echo -e "\n\n====\nALKiln ERROR - could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
       if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
       shell: bash
 
-    # Install on server
-    - name: "ALKiln: Install the GitHub package onto the server"
+    # Server installations - find folders and save session vars
+    - name: "ALKiln setup info: Install the GitHub package onto the server"
       if: ${{ inputs.INSTALL_METHOD == 'server' }}
       run: alkiln-server-install
       shell: bash
-    - run: echo -e "\n\n====\nALKiln could not install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
+    - name: "ALKiln setup ERROR"
+      run: echo -e "\n\n====\nALKiln ERROR - could not install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
       if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
       shell: bash
 
     # run tests
-    - name: "ALKiln: Run tests"
+    - name: "ALKiln info: Run tests"
       if: ${{ success() }}
       run: alkiln-run ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
       shell: bash
     
     # on playground, delete project
-    - name: "ALKiln: Try to delete the project from the playground of the docassemble test account."
+    - name: "ALKiln info: Try to delete the project from the playground of the docassemble test account."
       if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-takedown
       shell: bash
     
     # Upload artifacts that subscribers can download on the Actions summary page
-    - name: "ALKiln: Upload artifacts folder"
+    - name: "ALKiln info: Upload artifacts folder"
       if: ${{ always() }}
       uses: actions/upload-artifact@v3
       with:
         name: ${{ env.ARTIFACT_NAME }}
         path: ./alkiln-*
 
+    - run: echo "ALkiln finished running tests"
+      shell: bash
+
 # ##################################
 # # A developer's workflow should look similar to the below.
 # # In place of `uses: suffolkLITLab/ALKiln@v5`, they
@@ -123,10 +143,8 @@ runs:
 #     runs-on: ubuntu-latest
 #     name: Run interview tests
 #     steps:
-#       - uses: actions/checkout@v3
 #       - name: Use ALKiln to run tests
 #         uses: suffolkLITLab/ALKiln@v5
 #         with:
 #           SERVER_URL: "${{ secrets.SERVER_URL }}"
 #           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}"
-#       - run: echo "Finished running ALKiln tests"

package/action_for_github_server/action.yml

@@ -1,4 +1,4 @@
-name: "ALKiln/github_server: Isolated docassemble tests"
+name: "ALKiln isolated GitHub docassemble server tests"
 description: "Download and start up a temporary docassemble server on GitHub's servers, in an isolated environment. Avoids docassemble reload errors and other external factors."
 
 # If we want to control the version of the docassemble image, we'd have
@@ -40,9 +40,10 @@ outputs:
 runs:
   using: "composite"
   steps:
+      # Place the root directory in this branch
       - uses: actions/checkout@v3
 
-      - name: "ALKiln github_server - Set environment variables"
+      - name: "ALKiln GitHub server - Set environment variables"
         run: |
           echo "DA_ADMIN_API_KEY=abcd1234abcd1234abcd5678abdc5678" >> $GITHUB_ENV
           echo "MAX_SECONDS_FOR_DOCKER=${{ inputs.MAX_SECONDS_FOR_DOCKER }}" >> $GITHUB_ENV
@@ -57,18 +58,18 @@ runs:
           echo "DA_ADMIN_PASSWORD=$DA_ADMIN_PASSWORD" >> "$GITHUB_OUTPUT"
         shell: bash
 
-      - name: "ALKiln github_server - Get config"
+      - name: "ALKiln GitHub server - Get config"
         run: |
-          # Info: config values
+          # ALKiln GitHub server info: config values
           mkdir /tmp/config
           # Worth making this silent by defining a variable with > /dev/null...?
           if [ -n "${{ inputs.CONFIG_CONTENTS }}" ]
           then
-            echo "ALKiln github_server - The developer did provide a custom docassemble config file as an input into this action."
+            echo "ALKiln GitHub server - The developer did provide a custom docassemble config file as an input into this action."
             echo "${{ inputs.CONFIG_CONTENTS }}" > /tmp/config/myconfig.yml
             echo "CONFIG_ARGS=--env DA_CONFIG=/tmp/config/myconfig.yml --volume /tmp/config:/tmp/config " >> $GITHUB_ENV
           else
-            echo "ALKiln github_server - The developer did NOT provide a custom docassemble config file as an input into this action. Docassemble will use its default config."
+            echo "ALKiln GitHub server - The developer did NOT provide a custom docassemble config file as an input into this action. Docassemble will use its default config."
             echo "CONFIG_ARGS=" >> $GITHUB_ENV
           fi
         shell: bash
@@ -84,7 +85,7 @@ runs:
       # Define the var to prevent/show docker output
       - name: Env var for showing docker output
         run: |
-          # Info: Docker logs visibility decision
+          # ALKiln GitHub server info: Docker logs visibility decision
           if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
             echo "OUTPUT_DOCKER=${{ inputs.SHOW_DOCKER_OUTPUT }}" >> $GITHUB_ENV
           else
@@ -95,20 +96,20 @@ runs:
       # Messages about output
       - if: ${{ env.OUTPUT_DOCKER == 'false' }}
         run: |
-          # Info: no output
-          printf '===\nALKiln github_server - GitHub will now stop showing output to avoid possibly showing details about your config. If you want to get output to see more of what is going on, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "true". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
+          # ALKiln GitHub server info: no output
+          printf '===\nALKiln GitHub server - GitHub will now stop showing output to avoid possibly showing details about your config. If you want to get output to see more of what is going on, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "true". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
         shell: bash
       - if: ${{ env.OUTPUT_DOCKER == 'true' }}
         run: |
-          # Info: show output
-          printf '===\nALKiln github_server - GitHub will now show the output of docker creation. ALKiln cannot control this output. If you want to prevent output, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "false". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
+          # ALKiln GitHub server info: show output
+          printf '===\nALKiln GitHub server - GitHub will now show the output of docker creation. ALKiln cannot control this output. If you want to prevent output, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "false". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
         shell: bash
 
       # No output
-      - name: "ALKiln github_server - Download and start docker silently"
+      - name: "ALKiln GitHub server - Download and start docker silently"
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
         run: |
-          # Info: Silent docker pull/run
+          # ALKiln GitHub server info: Silent docker pull/run
           docker pull jhpyle/docassemble > /dev/null 2>&1
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="${{ env.DA_ADMIN_EMAIL }}" \
@@ -119,10 +120,10 @@ runs:
                      --memory="4gb" -d -p 80:80 jhpyle/docassemble > /dev/null 2>&1
         shell: bash
       # With output
-      - name: "ALKiln github_server - Download and start docker"
+      - name: "ALKiln GitHub server - Download and start docker"
         if: ${{ env.OUTPUT_DOCKER == 'true' }}
         run: |
-          # Info: Docker pull/run
+          # ALKiln GitHub server info: Docker pull/run
           docker pull jhpyle/docassemble
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="${{ env.DA_ADMIN_EMAIL }}" \
@@ -136,13 +137,13 @@ runs:
       # Show the time it takes to start the server.
       - if: ${{ env.OUTPUT_DOCKER == 'false' }}
         run: |
-          # Info: temporary visible logs
-          echo "ALKiln github_server - ALKiln will show safe ALKiln-only output temporarily as ALKiln waits for the server to start"
+          # ALKiln GitHub server info: temporary visible logs
+          echo "ALKiln GitHub server - ALKiln will show safe ALKiln-only output temporarily as ALKiln waits for the server to start"
         shell: bash
 
-      - name: "ALKiln github_server - Wait for server to start"
+      - name: "ALKiln GitHub server - Wait for server to start"
         run: |
-          # ALKiln github_server - Wait for server to start
+          # ALKiln GitHub server - Wait for server to start
 
           # Reset the SECONDS variable
           SECONDS=0
@@ -151,23 +152,23 @@ runs:
 
           response="start"
           while [[ $response != *"200"* ]]; do
-            echo "ALKiln github_server - Time elapsed: $SECONDS seconds"
+            echo "ALKiln GitHub server - Time elapsed: $SECONDS seconds"
 
             # Check if max seconds till loading has passed
             if [[ $SECONDS -ge $MAX_SECONDS_FOR_DOCKER ]]; then
-              echo "ALKiln github_server Error: Timed out waiting for docker container to serve the site. If you want to give your docker container more timem to install, set the MAX_SECONDS_FOR_DOCKER input for this action."
+              echo "ALKiln GitHub server Error: Timed out waiting for docker container to serve the site. If you want to give your docker container more timem to install, set the MAX_SECONDS_FOR_DOCKER input for this action."
               exit 1
             fi
 
             # Set the variable to a new string value in each iteration
             response=$(curl -o /dev/null -s -w "%{http_code}\n" http://localhost:80/health_check?ready=1)
-            echo "ALKiln github_server - response is $response"
+            echo "ALKiln GitHub server - response is $response"
 
             # Check if the string includes the desired text
             if [[ $response == *"200"* ]]; then
-              echo "ALKiln github_server - Success! The docker container is ready!"
+              echo "ALKiln GitHub server - Success! The docker container is ready!"
             else
-              echo "ALKiln github_server - The docker container is not ready yet. Will check again in 30 seconds."
+              echo "ALKiln GitHub server - The docker container is not ready yet. Will check again in 30 seconds."
               sleep 30
             fi
 
@@ -178,8 +179,8 @@ runs:
       - name: Message about docassemble install output
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
         run: |
-          # Info: Silent install message
-          echo "ALKiln github_server - ALKiln will now prevent output again"
+          # ALKiln GitHub server info: Silent install message
+          echo "ALKiln GitHub server - ALKiln will now prevent output again"
         shell: bash
 
       # Don't rely on the environment's version of python
@@ -206,18 +207,18 @@ runs:
 
       # Upload artifacts that devs can download on the Actions summary page
       # Only if the developer wants to get that info, though
-      - name: "ALKiln github_server - Get path names with date and time"
+      - name: "ALKiln GitHub server - Get path names with date and time"
         if: ${{ always() && env.OUTPUT_DOCKER == 'true' }}
         run: |
           echo "GITHUB_SERVER_LOG_FILE_NAME=/tmp/alkiln_docker_logs-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC.txt" >> $GITHUB_ENV
           echo "GITHUB_SERVER_ARTIFACT_NAME=alkiln_github_server-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
         shell: bash
-      - name: "ALKiln github_server - Docker output"
+      - name: "ALKiln GitHub server - Docker output"
         if: ${{ always() && env.OUTPUT_DOCKER == 'true' }}
         run: |
           echo "$(docker output docassemble_container)" > "${{ env.GITHUB_SERVER_LOG_FILE_NAME }}"
         shell: bash
-      - name: "ALKiln github_server - Upload artifacts folder"
+      - name: "ALKiln GitHub server - Upload artifacts folder"
         if: ${{ always() && env.OUTPUT_DOCKER == 'true' }}
         uses: actions/upload-artifact@v3
         with:
@@ -225,7 +226,13 @@ runs:
           path: ${{ env.GITHUB_SERVER_LOG_FILE_NAME }}
 
       - run: |
-          # Info: End silent output
-          echo "ALKiln github_server - ALKiln will show output again"
+          # ALKiln GitHub server info: End silent output
+          echo "ALKiln GitHub server - ALKiln will show output again"
+        if: ${{ always() && env.OUTPUT_DOCKER == 'false' }}
+        shell: bash
+
+      - run: |
+          # ALKiln GitHub server info: Done
+          echo "ALKiln GitHub server - ALKiln will show output again"
         if: ${{ always() && env.OUTPUT_DOCKER == 'false' }}
         shell: bash

package/lib/docassemble/docassemble_api_REST.js

@@ -1,14 +1,12 @@
 const axios = require('axios');
-const qs = require('qs');
 
+// Ours
 const session_vars = require('../utils/session_vars' );
 
 /* Requests to make to the developer's docassemble server.
 *   As close to plain requests as we can get so we don't have
 *   to think about this file again.
-* Notes:
-*   - We are not using `.create()` because we want to get
-*   the environment variables fresh every time. */
+*/
 
 let da = {};
 module.exports = da;
@@ -33,82 +31,6 @@ da.get_dev_id = async function ( timeout ) {
 };  // Ends da.get_dev_id()
 
 
-// node -e 'require("./lib/docassemble/docassemble_api_REST.js").create_project( "create1" )'
-da.create_project = async function ( project_name, timeout ) {
-  /* Create a new project on the user's da server. */
-  let options = {
-    method: 'POST',
-    headers: {'X-API-Key': session_vars.get_dev_api_key()},
-    url: `${ session_vars.get_da_server_url() }/api/playground/project`,
-    data: qs.stringify({
-      project: project_name,
-    }),
-    timeout: timeout,
-  };
-
-  try {
-    return await axios.request( options );
-  } catch (error) {
-    let response = error.response || {data: null}
-    throw {...error.toJSON(), data: response.data};
-  }
-};  // Ends da.create_project()
-
-
-// node -e 'require("./lib/docassemble/docassemble_api_REST.js").pull()'
-da.pull = async function ( timeout ) {
-  /* Pull github code into an existing Project. */
-  let options = {
-    method: 'POST',
-    headers: {'X-API-Key': session_vars.get_dev_api_key()},
-    url: `${ session_vars.get_da_server_url() }/api/playground_pull`,
-    data: qs.stringify({
-      project: session_vars.get_project_name(),
-      github_url: session_vars.get_repo_url(),
-      branch: session_vars.get_branch_name(),
-    }),
-    timeout: timeout,
-  };
-
-  try {
-    return await axios.request( options );
-  } catch (error) {
-    let response = error.response || {data: null}
-    throw {...error.toJSON(), data: response.data};
-  }
-};  // Ends da.pull()
-
-
-da.has_playground_task_finished = async function ( task_id, timeout ) {
-  return await da.has_task_finished( "/api/restart_status", task_id, timeout);
-}
-
-da.has_package_task_finished = async function ( task_id, timeout ) {
-  return await da.has_task_finished( "/api/package_update_status", task_id, timeout);
-}
-
-// node -e 'require("./lib/docassemble/docassemble_api_REST.js").has_task_finished()'
-da.has_task_finished = async function ( api_endpoint, task_id, timeout ) {
-  /* Check task status based on `task_id`. */
-  let options = {
-    method: 'GET',
-    headers: {'X-API-Key': session_vars.get_dev_api_key()},
-    url: `${ session_vars.get_da_server_url() }${ api_endpoint }`,
-    params: {
-      task_id: task_id,
-    },
-    timeout: timeout,
-  };
-
-  try {
-    return await axios.request( options );
-  } catch (error) {
-    let response = error.response || {data: null}
-    throw {...error.toJSON(), data: response.data};
-  }
-};  // Ends da.has_task_finished()
-
-
 // node -e 'require("./lib/docassemble/docassemble_api_REST.js").delete_project( "create1" )'
 da.delete_project = async function ( timeout ) {
   /* Delete a project on the user's da server. */
@@ -160,4 +82,4 @@ da.__delete_projects_starting_with = async function ( base_name, starting_num=1,
     }
     name_incrementor++;
   }
-}; // Ends da_i.__delete_projects_starting_with()
+}; // Ends da.__delete_projects_starting_with()

package/lib/docassemble/docassemble_api_interface.js

@@ -12,7 +12,7 @@ const time = require('../utils/time');
 //    do it before trying to load a page.
 
 // TODO: How can we test busy server stuff properly? Especially down
-// to specific functions, like `.pull()` which run in a very small
+// to specific functions, which can run in a very small
 // window.
 
 /** Notes:
@@ -171,287 +171,10 @@ da_i.get_dev_id = async function ( dev_id_options ) {
   return dev_id;
 };  // Ends da_i.get_dev_id();
 
-
-// node -e 'require("./lib/docassemble/docassemble_api_interface.js").validate_api_key()'
-da_i.validate_api_key = async function ( api_key_options ) {
-  /** Make sure the api key is the right one for this server.
-  *   See https://docassemble.org/docs/api.html#user. */
-
-  log.info({ pre: `Checking the testing account's API key.` });
-
-  // Default timeouts
-  api_key_options = api_key_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
-
-  try {
-
-    // There's only one possible success result
-    // As long as this succeeds, we're good
-    await _da_REST.get_dev_id( api_key_options.timeout );
-    log.info({ pre: `Your testing account's API key is perfectly valid on this server.` });
-    return true;
-
-  } catch ( error ) {
-    // There's only one possible sever response error
-    if ( error.response && error.response.status === 403 ) {
-      // Throw in here, or at the caller?
-      log.error({
-        pre: `The API key in the GitHub secret DOCASSEMBLE_DEVELOPER_API_KEY `
-        + `failed on this server with "Access Denied". Are you sure your `
-        + `DOCASSEMBLE_DEVELOPER_API_KEY secret is set to the API key for `
-        + `the docassemble account that runs the tests on this server? `
-        + `Are you sure your SERVER_URL GitHub secret is set to the server `
-        + `address on which this testing account exists?`
-        + `To update your GitHub secrets, either set this repository's `
-        + `secrets at ${ session_vars.get_repo_url() }/settings/secrets `
-        + `or ask your GitHub organization admin to set the `
-        + `organization's secrets.`
-      });
-    }  // ends 403 message
-    throw error;
-  }  // ends try to get dev_id
-};  // Ends da_i.validate_api_key()
-
-
-// node -e 'require("./lib/docassemble/docassemble_api_interface.js").loop_to_create_project()'
-da_i.loop_to_create_project = async function( creation_options ) {
-  /** Create a docassemble Project on the docassemble server's account.
-  *    Loop through potential project names until we find one that
-  *    isn't already taken and then use that name to create the Project. */
-
-  // Defaults
-  creation_options = creation_options || {};
-  let timeout = creation_options.timeout || DEFAULT_MAX_REQUEST_MS;
-  let max_tries = creation_options.max_tries || 15;
-  let wait_seconds = creation_options.wait_seconds || 5;
-
-  let project_name = null;
-  // Unlikely, but 2 devs could run locally and create the same Project name
-  let num_tries = 0;
-
-  // Try to create a project. If the project name is already taken, increment and loop again.
-  while ( num_tries <= max_tries ) {
-    num_tries++;
-    try {
-
-      // Try next name that could be unique. Must remove all non-valid characters
-      // TODO: This sanitization is already done in session_vars, so remove it from here
-      project_name = session_vars.get_project_base_name().replace(/[^A-Za-z0-9]/g, '') + `${Date.now()}`;
-      log.info({ pre: `Trying to create a docassemble Project with the name ${ project_name }` });
-      let response = await _da_REST.create_project( project_name, timeout );
-      log.info({ pre: `The docassemble server is ready. Created a Project named ${ project_name }` });
-      // If succeeded in creating project, return the name that worked
-      return project_name;
-
-    } catch ( error ) {
-      // TODO: Make a `normalize_ajax_responses_and_errors()`?
-      let response = error;
-
-      if ( response && response.data ) {
-        if ( response.data.includes( `Invalid project` ) ) {
-          if ( num_tries < max_tries ) {
-            // A non-unique project name. Try the next project name.
-            continue;
-
-          } else {
-            // On the last loop, failed because there were too many project
-            // names already taken
-            log.error({
-              pre: `There were already ${ max_tries } projects with the base `
-              + `name ${ session_vars.get_project_base_name() }. If you need to allow `
-              + `more, file an issue at https://github.com/SuffolkLITLab/ALKiln/issues.`
-            });
-            throw( error );
-          }
-
-        // ends "Invalid project" error
-        } else {
-          // Other response errors should be thrown with link to docs
-          log.error({
-            type: `docassemble ${ response.status } "${ response.data }"`,
-            pre: `See https://docassemble.org/docs/api.html#playground_post_project.`
-          });
-          throw ( error );
-        }
-      } else { // for if error.response
-
-        // If it's a timeout error, server is busy. Try again after waiting.
-        // Why are we using `max_tries` for timeout error as well?
-        if ( is_timeout_error( error ) && num_tries < max_tries ) {
-          log.info({ pre: `The docassemble server was busy when we tried to `
-            + `create the Project. Attempt ${ num_tries } of `
-            + `${ max_tries }. Will try again in ${ wait_seconds } seconds.` });
-          num_tries--;  // Don't count this try
-          await time.waitForTimeout( wait_seconds * 1000 );
-          continue;
-
-        // A non-timeout, non-server error should just be thrown
-        } else {
-          log.error({ pre: `Ran into unexpected error when trying to create the Project.` });
-          throw error;
-
-        }  // ends type of non-response error
-      }  // ends type of response error
-    }  // ends try
-  }  // ends while
-};  // Ends da_i.loop_to_create_project()
-
-
-// node -e 'require("./lib/docassemble/docassemble_api_interface.js").pull()'
-da_i.pull = async function ( pull_options ) {
-  /** Pull github code into an existing Project. */
-
-  log.info({ pre: `Trying to pull code from the "${ session_vars.get_branch_name() }" branch.` });
-
-  // Default timeouts
-  let { timeout } = pull_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
-
-  try {
-
-    let response = await _da_REST.pull( timeout );
-
-    // If server didn't need to restart
-    if ( response && response.status === 204 ) {
-      log.info({ pre: `Your Docassemble server finished pulling the package's code.` });
-      return null;
-    }
-
-    // If server needed to restart because of the pulled code
-    if ( response && response.status === 200 ) {
-      log.debug({ pre: `Pull task id: ${ response.data.task_id }` });
-      return response.data.task_id;
-    }
-
-  } catch ( error ) {
-    // Pulling should not error
-    log.error({ pre: `Pulling into the docassemble Project ran into an unexpected error.` });
-    log.debug({ pre: `See https://docassemble.org/docs/api.html#playground_pull.` });
-    throw error;
-  }
-};  // Ends da_i.pull()
-
-// node -e 'require("./lib/docassemble/docassemble_api_interface.js").has_task_finished()'
-da_i.has_task_finished = async function ( api_endpoint, task_id, options ) {
-  /** Check task status if it exists. If not, return true as task did
-  *    not require a server restart. See da_i.pull().
-  *    See https://docassemble.org/docs/api.html#restart_status. */
-
-  // Defaults
-  let { timeout } = options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
-
-  try {
-
-    // If server did need to restart, check if it's done.
-    let response = await _da_REST.has_task_finished( api_endpoint, task_id, timeout );
-    log.debug({ pre: `Task status: ${ response.status }. Docassemble status text: ${ response.data.status }. Task id: ${ task_id }` });
-    
-    if ( response.data.status === 'completed' ) {
-      return true;
-    
-    } else if ( response.data.status === 'working' ) {
-      log.info({ pre: `The docassemble server is uploading the package.` });
-      return false;
-
-    } else if ( response.data.status === 'unknown' ) {
-      // Server is working, but status 'unknown'? Bad design, but this
-      // does get returned when install packages, so return true
-      log.info({
-        pre: `\`task_id\` "${ task_id }" has expired. If it's been `
-          + `less than 1 hour since the task started, the task is `
-          + `complete. See https://docassemble.org/docs/api.html#restart_status.`,
-        data: response.data,
-      });
-      return true;
-    }  // ends status type
-
-  } catch ( error ) {
-    // Timeout means the server is busy.
-    if ( is_timeout_error( error ) ) {
-      log.info({ pre: `The docassemble server is still uploading the package.` });
-      return false;
-    }
-
-    log.error({ pre: `Tried to check that the package was uploaded, but ran into an unexpected error.` });
-    throw error;
-  }  // ends try to check for server done restarting
-
-};  // Ends da_i.has_task_finished()
-
-da_i.wait_for_playground_to_restart = async ( task_id, options ) => {
-  return await da_i.wait_for_server_to_restart( "/api/restart_status", task_id, options );
-};
-
-da_i.wait_for_package_to_restart = async ( task_id, options ) => {
-  return await da_i.wait_for_server_to_restart( "/api/package_update_status", task_id, options );
-};
-
-da_i.wait_for_server_to_restart = async ( api_endpoint, task_id, options ) => {
-  /** Wait for the server to finish restarting in case a module needs to load.
-  *     This is a polling function because things may be returned
-  *     that aren't equivalent to the server being done with a task. */
-  log.info({ pre: `Docassemble is pulling this package. The task_id is `
-    + `"${ task_id }". A task_id is usually created for a package `
-    + `with a module. It can take a few minutes to finish uploading.` });
-
-  // Base default
-  options = options || {};
-  // Default timeout
-  let timeout = options.timeout || DEFAULT_MAX_REQUEST_MS;
-  // Other defaults
-  let default_wait_between_loops = 4 * 1000;
-  let default_wait_for_response = 1 * 1000;
-  let default_max_loops = timeout/( default_wait_between_loops + default_wait_for_response );
-  // Actual values
-  let wait_between_loops = options.wait_between_loops || default_wait_between_loops;
-  let wait_for_response = options.wait_for_response || default_wait_for_response;
-  let max_loops = options.max_loops || default_max_loops;
-
-  // Flags for stopping the `while` loop
-  let num_tries = 0;
-  let done_restarting = false;
-
-  // Why loop instead of one long timeout? Because it might not just hang.
-  // We might get a return value that's just `waiting`, meaning the
-  // task is not done.
-  while ( !done_restarting && num_tries <= max_loops ) {
-    num_tries++;
-    // Wait only a short time for the task to finish, not the full default timeout
-    done_restarting = await da_i.has_task_finished( api_endpoint, task_id, { timeout: wait_for_response } );
-    if ( !done_restarting ) {
-      if ( num_tries < max_loops ) {
-        // Show a slightly different message after a number of tries to reassure
-        // users we're still paying attention
-        let msg_start = `Not yet complete`;
-        if ( num_tries > 3 ) { msg_start = `Still not complete`; }
-
-        // When the server is busy, the task timeout causes this loop to actually
-        // take 5 seconds to complete, but this only waits for 4. I'm not sure how
-        // to make that clear
-        log.info({ pre: `${ msg_start }. Check ${ num_tries } of ${ max_loops }. `
-          + `Will check again in ${( wait_between_loops + wait_for_response )/1000 } seconds.`
-        });
-        await time.waitForTimeout( wait_between_loops );
-
-      } else {
-        // This is our last round, let's wrap it up
-        let server_msg = `ALKiln setup: It seems like the docassemble server `
-          + `didn't finish uploading the code after ${ timeout/1000 } `
-          + `seconds. Some things you can try: check your server is up, try `
-          + `re-running the test, and try pulling the package manually `
-          + `into the playground.`;
-          // Add link to docs once the docs are more comprehensive
-        throw( server_msg );
-      }  // ends if ran out of tries
-    }  // ends if done_restarting
-  }  // ends while not done restarting
-
-  log.info({ pre: `The docassemble server has uploaded your package.` });
-};  // Ends da_i.wait_for_server_to_restart()
-
-
-// Delete the Project
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").delete_project( "create1" )'
 da_i.delete_project = async function ( delete_options ) {
-  /** Delete a project on the user's da server. */
+  /** Delete a project on the user's da server. Do we need to watch
+  *   for a timeout? */
 
   // Defaults
   let { timeout } = delete_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };

package/lib/docassemble/server_install.js

@@ -7,6 +7,7 @@ const fg = require('fast-glob');
 const server_install = async () => {
   session_vars.save_install_method(`server`);
 
+  // Get path to folders inside repo main "docassemble" folder
   let current_dir = process.cwd();
   let path = `${ current_dir }/docassemble/*`;
   let dirs = fg.sync(
@@ -19,6 +20,7 @@ const server_install = async () => {
 
   let folders = dirs.map(function (dir) { return dir.split('/').pop(); })
 
+  // Get names of all folders in repo "docassemble" folder
   let chosen_folder = folders[0];
   if ( folders.length === 0 ) {
     let msg = `There are 0 folders at ${path}. Tests won't run.`;

package/lib/docassemble/setup.js

@@ -1,50 +1,60 @@
 #!/usr/bin/env node
 
-const da_i = require('./docassemble_api_interface');
-const log = require('../utils/log');
-const session_vars = require('../utils/session_vars' );
-const files = require('../utils/files' );
+// TODO: Rename to playground_install?
 
+const child_process = require(`child_process`);
+
+const log = require(`../utils/log`);
+const session_vars = require(`../utils/session_vars` );
 
 const setup = async () => {
-  /* In the docassemble testing account identified by the
+  /** In the docassemble testing account identified by the
   *   DOCASSEMBLE_DEVELOPER_API_KEY secret, create a new Project,
   *   pull code into that project, and, if needed, wait for the
-  *   server to restart. */
-  log.info({ type: `setup`, pre: `Starting to upload this package to `
-    + `a new Project in the server's testing account.` });
-
-  // Check that API key is valid. Will error if it is invalid.
-  // Should the error be thrown here?
-  await da_i.validate_api_key();
-
-  // Create a project on the da server's account with a unique name then
-  // store it locally for later deleting the project. 
-  let project_name = null;
-  // Explicit try-catch prevents "Unhandled promise rejection error"
-  // avoids showing confusing node errors to users that they shouldn't have to fix
-  try {
-    project_name = await da_i.loop_to_create_project();
-    log.info({type: `setup`, pre: `Created a Project named ${ project_name }`});
-  } catch (error) {
-    log.error({type: `setup`, pre: `an unexpected error occurred while trying to create a docassemble project in the user's account`, data: JSON.stringify(error, null, 4)})
-    // we don't re-throw the exception, so make sure to exit with 1 to let Github Actions know the script failed
-    process.exitCode = 1;
-    return;
-  }
-  // Once the name is created, save that name to a local file.
+  *   server to reload.
+  */
+  
+  // Make and save project name
+  let project_name = session_vars.get_project_base_name().replace(/[^A-Za-z0-9]/g, '') + `${Date.now()}`;
   session_vars.save_project_name( project_name );
 
-  // Pull code and wait for server restart to finish if needed
-  let task_id = await da_i.pull();
-  // Task id will be null if server did not need to restart
-  if ( task_id ) {
-    await da_i.wait_for_playground_to_restart( task_id );
+  log.info({ type: `setup`, pre: `Starting to upload this package to `
+    + `a new Project called ${project_name} in the Playground `
+    + `of your server's testing account. It may take a couple of minutes.` });
+
+  // dainstall . --apiurl https://site.org --apikey $API_KEY --playground --project=name
+  // I think this won't run on windows? Why do I think this? Where on the
+  // internet did I find this. Some command here or in dainstall doesn't
+  // work on windows.
+  let result = child_process.spawnSync(
+    `dainstall`,
+    [
+      `.`, `--apiurl`, session_vars.get_da_server_url(),
+      `--apikey`, session_vars.get_dev_api_key(),  // validates api key
+      `--playground`, `--project=${ project_name }`
+    ],
+    // Prints messages from the process to the console while it's running
+    { stdio: 'inherit', }
+  );
+
+  // 403 is invalid API key, but I'm not sure how to output
+  // the response to find out the error code
+
+  if ( result.status !== 0 ) {
+    log.error({
+      type: `setup`,
+      pre: `Status code ${ result.status }. Could not dainstall this package on your server. See above for more details.`
+    });
+    throw(result.stderr);
   }
 
-  // Finish
-  log.info({ type: `setup`, pre: `Success! Test setup has finished successfully.` });
+  log.info({
+    type: `setup`,
+    pre: `Success! ALKiln created a Project in your Playground named "${ project_name }"` 
+  });
 };  // Ends setup();
 
 
+// Before everything, make sure all the required env vars exist
+session_vars.validateEnvironment();
 setup();

package/lib/steps.js

@@ -67,6 +67,10 @@ to detect that.
 regex thoughts: https://stackoverflow.com/questions/171480/regex-grabbing-values-between-quotation-marks
 */
 
+// Make sure all the required env vars exist. Required to be
+// here as well as `setup`` specifically for local development.
+session_vars.validateEnvironment();
+
 // Hoping that most load and download times will be under 30 seconds.
 // TODO: Check what average load and download times are in our current interviews.
 let default_timeout = 30 * 1000

package/lib/utils/session_vars.js

@@ -371,8 +371,6 @@ session_vars.validateEnvironment = function() {
   errorMessage = errorMessage.trim();
 
   if (errorMessage !== '') {
-    throw new ReferenceError(`ALKiln error: ${errorMessage}`);
+    throw new ReferenceError(`ALKiln error:\n${errorMessage}`);
   }
 };
-
-session_vars.validateEnvironment();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {

package/.github/workflows/test_tests.yml

@@ -1,73 +0,0 @@
-name: Test the tests
-
-on:
-  push:
-  workflow_dispatch:
-    inputs:
-      tags:
-        required: False
-        description: 'Optional. Use a "tag expression" specify which tagged tests to run (https://cucumber.io/docs/cucumber/api/#tag-expressions)'
-        default: ''
-
-jobs:
-
-  puppeteer-tests:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [18.x]
-
-    env:
-      BASE_URL: ${{ secrets.SERVER_URL }}
-      PLAYGROUND_EMAIL: ${{ secrets.PLAYGROUND_EMAIL }}
-      PLAYGROUND_PASSWORD: ${{ secrets.PLAYGROUND_PASSWORD }}
-      PLAYGROUND_ID: ${{ secrets.PLAYGROUND_ID }}
-      DOCASSEMBLE_DEVELOPER_API_KEY: ${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}
-      USER1_EMAIL: ${{ secrets.USER1_EMAIL }}
-      USER1_PASSWORD: ${{ secrets.USER1_PASSWORD }}
-      SECRET_VAR1: secret-var1-value
-      SECRET_VAR2: secret-var2-value
-      SECRET_FOR_MISSING_FIELD: secret for missing field
-      _ORIGIN: github
-
-    name: Run Puppeteer tests
-    steps:
-      - name: Set Github-related environment variables
-        run: |
-          echo "REPO_URL=${{ github.server_url }}/${{ github.repository }}" >> $GITHUB_ENV
-          echo "BRANCH_PATH=${{ github.ref }}" >> $GITHUB_ENV
-      - name: Set name of artifact folder with date and UTC 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
-        run: |
-          echo "ARTIFACT_NAME=alkiln-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
-          echo "UNIT_TESTS_ARTIFACT_NAME=_alkiln-misc-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
-      # For the testing repo, the `REPO_URL` is that of a different repo and is created in `env:`
-      - run: echo "Repo address is $REPO_URL"
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup environment
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm install
-      - run: npm run setup
-      - run: npm run test ${{ github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
-      # Artifacts
-      - name: upload unit tests artifacts folder
-        uses: actions/upload-artifact@v3
-        # This will upload even if a previous step has failed
-        if: ${{ always() }}
-        with:
-          name: ${{ env.UNIT_TESTS_ARTIFACT_NAME }}
-          path: ./_alkiln-*
-      - name: upload integration tests artifacts folder
-        uses: actions/upload-artifact@v3
-        if: ${{ always() }}
-        with:
-          name: ${{ env.ARTIFACT_NAME }}
-          path: ./alkiln-*
-      # Delete Playground Project and project name file
-      - name: Cleanup
-        if: ${{ always() }}
-        run: npm run takedown