Banbury Zendesk Theme

This repository contains the custom Zendesk Help Center theme used by JustServe. It is built using Handlebars (.hbs), SCSS, TypeScript, and JavaScript (bundled via Rollup).

Required Tools

To work on this theme, you must acquire the following tools:

Git	Install Git and configure your local SSH credentials on GitHub. MFA must be enabled on your GitHub account in order to join the JustServe-Resources GitHub organization.
IDE	Install Visual Studio Code, a JetBrains IDE, or a similarly decent IDE.
Node.js	Refer to nodejs.org to find how to install this for your OS.
Yarn	Install globally via npm (npm install -g yarn). (npm is installed when you install Node.js)
ZCLI (Zendesk CLI)	Refer to the Zendesk ZCLI Documentation for setup, authentication, and preview usage.
Firefox Extension	Install Export Cookies on Firefox. This is required for end-to-end testing.

How to contribute

1. Install local project dependencies:

   yarn install

2. Start the local development server:

   yarn start

   This command continuously watches /src/ and /styles/ folders and runs Rollup to compile them into the /assets/ directory.

Important Folder Rules

• templates/: Edit your Handlebars (.hbs) HTML structural files here.
• src/ and styles/: Edit raw JavaScript and CSS source code here.
• assets/: Do not edit files here. They are automatically generated and overwritten by Rollup.

Testing

Run Tests Against Sandbox Only

DO NOT RUN TESTS AGAINST PRODUCTION (justserve.zendesk.com). Tests are to only run against a Sandbox environment. Attempts to run tests against production will fail and your access to the JustServe GitHub repository and Zendesk may be removed.

Note

Checkout the Zendesk Developer Sandbox Documentation to procure and configure your own sandbox. Alternatively, you can email support@justserve.org to request access to the current shared Sandbox we are using, and we can provision you a test account with which you can login to the sandbox.

Playwright Tests

Caution

This authentication process will soon change to something more reliable

We use Playwright for automated UI tests. You must manually set your active browser cookies to allow playwright to work with Zendesk, albeit for only half a dozen tests or so.

1. Copy .env.example to .env and configure ZENDESK_TEST_HOST with your assigned Sandbox domain.
2. Open Firefox, log into the JustServe Zendesk Sandbox securely, and pass any captchas.
3. Click the Export Cookies extension and select "Export as cookies.txt".
4. Copy or save the downloaded file into the root folder of this repository, ensuring it is named exactly cookies-zendesk-com.txt. DO NOT COMMIT THIS FILE
5. Run the test suite:

   yarn test:e2e

Jest Tests

We use Jest for unit testing the javascript and typescript files. When running these tests, it is normal to see red text and warnings in the console output.

You should ignore these warnings and refer to the final test summary at the bottom of the output. Verify that the count of tests passing matches the total count of tests ran to ensure your tests are successful.