Persona Padlock

Welcome to Persona Padlock! This guide will walk you through setting up the development environment and getting started with contributing to the project.

Contributing

We follow the conventional commits specification for our PR titles. When creating a Pull Request, the title of the PR will be used as the commits will be squashed and merged in the main branch.

Therefore, it is mandatory to use conventional commit messages in the title of your PR. To enforce this, we use a GitHub action that checks the PR title for conventional commits.

We use this standard to help us correctly version the project and generate changelogs automatically.

For more information about conventional commits, you can refer to Conventional Commits Specification.

Setting Up the Development Environment

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js - version is defined in .nvmrc file
• Git

Getting Started

git clone [email protected]:talis/persona-padlock.git
cd persona-padlock

Enable pnpm

We use pnpm as the package manager for this project. If you don't have pnpm installed, you can enable it using corepack.

Corepack is a set of core utilities bundled with Node.js. It allows you to enable and run pnpm without needing to install it separately. Here's how you can enable pnpm via corepack:

corepack enable pnpm

This will enable pnpm using the package manager version specified in the package.json file.

Install Dependencies

pnpm install

Add Host Aliases:

To access the project via padlock.talis.local, and run the e2e tests you need to add the following host aliases:

• Mac/Linux: Edit /etc/hosts using a text editor with sudo privileges. Add the following line to the hosts file:

127.0.0.1   padlock.talis.local
127.0.0.1   fake-persona.talis.local

Add environment variables

Create a .env file in the root of the project and copy the contents of the .env.example file into it.

For the PERSONA_CLIENT_ID and PERSONA_CLIENT_SECRET variables, make sure you update these to be the standard local ones.

If intending to use the demo to perform authentication against Persona production, you need to update the following:

• PERSONA_PRODUCTION_CLIENT_ID
• PERSONA_PRODUCTION_CLIENT_SECRET

These credentials are used for the server-to-server authorize with alias LTI authentication and can be found in Keeper under the Persona Padlock - PKCE Auth Client - Production record.

For VITE_OAUTH_PROVIDER, set this to a value that matches a Persona auth provider you have setup locally. Padlock does not set them up itself. For example, if you have RL running, life would be a working auth provider and if you have Elevate running, talis would be a working auth provider.

Create a .env.test file in the root of the project and copy the contents of the .env.test.example file into it.

Start the Development Servers

pnpm start

This will start the frontend and backend servers and open the project in your default browser at https://padlock.talis.local:5000.

The backend server will be running at https://padlock.talis.local:5100.

Running Tests

To run the tests, use the following command:

pnpm test

or to run the tests in watch mode:

pnpm test:watch

e2e-tests

There are a 2 "flavours" of e2e tests that can be run depending on the environment you wish to target. Currently, we support a fake Persona service or Production. These must be run separately as the Production tests share a user and so cannot be run in parallel.

Stubbed Persona e2e tests: To run the end-to-end tests, use the following command:

pnpm test:e2e:fake-persona

# to run with UI enabled:
pnpm test:e2e:fake-persona:ui

Production Persona e2e tests: To run the end-to-end tests, the following needs to be completed:

Update .env.test:

• PRODUCTION_USERNAME - The username of the Auth0 production user for the test to login as
• PRODUCTION_PASSWORD - The password of the Auth0 production user

These values can be found in Keeper under the [Production] Persona Padlock Auth0 Credentials record.

Update .env file:

• PERSONA_PRODUCTION_CLIENT_ID
• PERSONA_PRODUCTION_CLIENT_SECRET

These credentials are used for the server-to-server authorize with alias LTI authentication and can be found in Keeper under the Persona Padlock - PKCE Auth Client - Production record.

Then run the following command:

pnpm test:e2e:prod-persona

# to run with UI enabled:
pnpm test:e2e:prod-persona:ui

In both cases this will start 2 servers using the pnpm test:e2e:start:servers command before running the tests

Linting & Formatting

Linting and formatting are done using ESLint and Prettier. You can run the linter using the following command:

pnpm lint

You can also automatically fix some linting issues by running:

pnpm lint:fix

You can run the formatter in check mode only using the following command:

pnpm prettier

You can also automatically fix some formatting issues by running:

pnpm prettier:fix

Or run both the linter and formatter using the following command:

pnpm format