doytsujin/sidekick

Pa11y Sidekick is a proposed replacement for Pa11y Dashboard

Pa11y Sidekick

This is a new project based around Pa11y, code-named "Sidekick". Pa11y Sidekick will be a modern and well thought out replacement for Pa11y Dashboard and Pa11y Webservice. What exactly is Pa11y Sidekick going to do? Still to be defined, but our rough proposal at this stage:

like Travis, but for a11y testing, and with graphs.

✨ Click here for the full proposal document, project roadmap, and FAQs ✨

---

Table Of Contents

• Requirements
• Deployment
• Running locally
• Configuration
• Contributing
• Architecture
• License

Requirements

This application requires Node.js 8+ and PostgreSQL 9.5+.

Deployment

Sidekick can run anywhere that meets the above requirements. The instructions for running locally can be used as a guide, but we also maintain several quick-starts for common deployment targets:

• Heroku:
  Deploy Sidekick to Heroku using a one-click button or a series of instructions: Heroku Deployment Guide

Running locally

1. Install dependencies:

   npm install

2. Create a database. If you have the psql command on your path then you can try running the following:

   make db-create

   Otherwise you may have to authenticate to create the database, the SQL you need to run is:

   CREATE DATABASE pa11y_sidekick

3. Run the database migrations:

   make db-migrate-up

4. Start the application in either production mode:

   make start

   or development mode (with auto reloading):

   make start-dev

5. Open the application and complete the setup steps in the interface: http://localhost:8080/

Configuration

Pa11y Sidekick is highly configurable. You can configure the application with the following environment variables:

• DASHBOARD_URL: We use this whenever we display the dashboard URL in the application. If set to null, we make intelligent guesses based on the request headers
  Default: null

• DATABASE_URL: A PostgreSQL connection string, used to connect to the database.
  Default: postgres://localhost:5432/pa11y_sidekick

• LOG_LEVEL: The lowest level of logs to output, one of error, warn, info, verbose, debug.
  Default: verbose in production and debug in development.

• NODE_ENV: The environment to run the application in, one of production, development, test.
  Default: development.

• PORT: The HTTP port to run the application on. If set to an empty string, a random port will be assigned.
  Default: 8080.

• REQUEST_LOG_FORMAT: The log format to use for request logging, one of morgan's predefined formats.
  Default: combined.

• SESSION_SECRET: The secret to encrypt session IDs with. If not specified, this will default to a UUID which means sessions will be destroyed every time the application restarts.
  Default: a UUID.

Pa11y Sidekick will first attempt to load an .env file in the root of the project and read configurations from there. You can copy the sample environment config as a starting point:

make config

Alternatively you can set environment variables before running your command. Here's an example:

LOG_LEVEL=debug PORT=1234 REQUEST_LOG_FORMAT=tiny make start

Contributing

There are many ways to contribute to Pa11y Sidekick, we cover these in the contributing guide for this repo.

If you're ready to contribute some code, clone this repo locally and commit your code on a new branch. It's useful to read the Architecture Guide before contributing.

Please write unit tests for your code, and check that everything works by running the following before opening a PR:

1. Create a database. If you have the psql command on your path then you can try running the following:

   make db-create-test

   Otherwise you may have to authenticate to create the database, the SQL you need to run is:

   CREATE DATABASE pa11y_sidekick_test

2. Run the following command to verify the code and run all of the tests (this can take a long time to run all of the integration tests):

   make ci

You can also run verifications and tests individually:

make verify              # Verify all of the code (JSHint/JSCS/Dustmite)
make test                # Run all tests
make test-unit           # Run the unit tests
make test-unit-coverage  # Run the unit tests with coverage
make test-integration    # Run the integration tests

Architecture

We maintain an Architecture Guide which outlines how the application works, and how everything fits together. It's strongly recommended that you read through it if you want to contribute. We're currently in the architecture stage of development so this application has very few features – it's purely a demo how how we want to build things.

If you have any feedback, we'd love to hear it! This architecture is not yet set in stone.

• Have an idea for a feature?
• Want to help out?
• Think we're doing this all wrong?

Raise an issue on this repo, or get in touch on Twitter (our DMs are open). Also, feel free to open a PR to suggest changes.

Licence

Licensed under the Lesser General Public License (LGPL-3.0).
Copyright © 2016–2017, Team Pa11y