Elisha Nuchi
31befe1d68
This is version 3 of the boilerplate, which makes significant changes to the build script and local development tooling. It replaces Webpack with Vite, which required some significant changes to how the local development setup works with Google Apps Script. A new dev-server-wrapper.html file is used as the wrapper app in development, which is a standalone html + js file instead of a React app. This reduces the need for a complex build step for the wrapper app. Instead the file is just copied over for each entrypoing and the file location is changed with a "replace" step. Due to the way Vite works, the html templates are changed a bit to support local development. Vite doesn't easily allow completely separate multiple builds, so some Vite plugins and custom plugins are written to support multiple entrypoints (sidebars/dialogs). The externalization for large packages is now handled in the Vite config instead of a plugin, and by manually adding in the script tags into the index.html templates. Additional changes here: - yarn is now used instead of npm as package manager - eslint configs are updated to support vite - GitHub workflows for tests are updated to use yarn and other minor changes such as node versions and OS. - A VS Code launch.json configuration is provided - Dev wrapper setup has been updated (see above description) - ES Modules (import/export) updated throughout - Unneeded packages supporting webpack configurations are removed. Many packages have been upgraded. NPM scripts have been updated to use yarn. - Removed `import React` due to Vite config. - Added script tags to each template since webpack externalization plugin is no longer used - Added <script type="module" src="./index.jsx"></script> to index.html templates to support Vite local development - Changed src/server/sheets.js to .ts typescript as exemplar - Updated tests to support yarn commands, Vite changes, and listening for Vite stdout triggers. - Add Vite-style tsconfig.json - README is updated
Running tests
Integration tests here are used to ensure the existing local development setup works across different platforms, and that new features do not break the functionality of the local development environment.
The "extended" local development integration test builds and deploys the local development setup needed to use hot reload functionality. It deploys the local setup to a spreadsheet inside a test Google account, runs a local development server, and checks that changes to the local files are reflected inside the spreadsheet's add-on, similar to how local development is intended to be used.
Jest is used to run the tests and compare images of the changes, and Puppeteer is used to control the browser. A test account and test spreadsheet need to be created and credentials need to be passed in through environment variables in order for this "extended" version to work. Example .env file variables are listed below. Since secret values cannot be used in PRs opened from forks, a "basic" integration test just loads the local development setup locally, instead of deploying to Google Sheets.
Extended integration test
In order to test the extended integration test locally you will need to create or use a test Google account. It's recommended you create an account solely for this purpose rather than using an existing account. You'll need to create a new project and include the following variables in the .env file in the root:
SHEET_URL = https://docs.google.com/spreadsheets/d/****************/edit#gid=0
EMAIL = myisolatedtestaccount@gmail.com
PASSWORD = testaccountpassword
TEST_RECOVERY_EMAIL = myisolatedtestaccountsrecoveryemail@gmail.com
# For image reporting only
S3_BUCKET_NAME = my-bucket-name
AWS_ACCESS_KEY_ID = A35D************
AWS_SECRET_ACCESS_KEY = slkf***********/234jdh**********
Make sure that you have followed the instructions to install local certs (see main README). The test will use Puppeteer to open the spreadsheet URL and log in to your account using your email and password provided. In case it doesn't recognize you it will ask for this account's recovery email -- you'll need to include this in the .env file as well.
Running the extended tests in the pipeline
To run the extended integration test in a pipeline using Github Actions, reference the .github/workflows directory. You'll need to add some additional environment variables through the repo secrets settings in order to get the full flow working:
DOT_CLASPRC - the .clasprs.json file from user directory containing clasp login credentials
DOT_CLASP - the .clasp.json file from this repo matching the test spreadsheet
TEST_ACCOUNT_EMAIL, TEST_RECOVERY_EMAIL, TEST_ACCOUNT_PASSWORD, TEST_SPREADSHEET_URL - see above variables
Additional notes
Stealth login
puppeteer-extra and puppeteer-extra-plugin-stealth are used to help log in to a Google account in the pipeline for the "extended" integration test. They are not easily compatible with the jest-puppeteer package, so a custom integration is used that is documented on jest's site here.
Generating certs in the pipeline
There are permissions issues running mkcert -install in Windows runners, so a powershell script in ./generate-cert.ps1 is used to generate the certs and enable https.
Jest open handles
There are issues with jest keeping handles open after all tests finish on Windows runners, so jest --forceExit is used to resolve them, although this flag may not be needed on certain platforms (like Mac OS).
Jest Image Snapshots
jest-image-snapshot is used to compare browser snapshots and detect discrepancies or regressions. Thresholds have been adjusted to allow for some variation across different platforms due to differences in font rendering and color profiles.
If a snapshot fails, a diff image is created in the diff_output directory, showing the comparison. If it fails in the pipeline it may be hard to see this diff. An Image Reporter class is used to upload diff images to an S3 bucket from the pipeline. This can be modified to use any image store. If used, make sure it is enabled in jest.config.js and that the necessary environment variables (AWS keys, bucket name, etc.) are added to .env file (see above section).