eq-cims-management-ui

eq-cims-management-ui

---

Table of Contents

• Getting Started
  • Pre-requisites
  • Installation
• Development
  • Run Application with Database and CIR FastAPI
  • Run All Tests
  • Run Unit Tests with Coverage
  • Run Functional Tests
  • Linting and Formatting
• Contributing
• License

Getting Started

To get a local copy up and running, follow these simple steps.

Pre-requisites

Ensure you have the following installed:

1. Python: Version specified in .python-version. We recommend using pyenv for managing Python versions.
2. Poetry: This is used to manage package dependencies and virtual environments.
3. Docker
4. Operation System: Ubuntu/MacOS

Installation

1. Clone the repository and install the required dependencies.

   git clone https://github.com/ONSdigital/eq-cims-management-ui.git

2. Install dependencies

   Poetry is used to manage dependencies in this project. For more information, read the Poetry documentation.

   To install all dependencies, including development dependencies, run:

   make install-dev

   To install only production dependencies, run:

   make install

   To install the ONS Design System using node (fuller details below):

   nvm install
   nvm use

   then run:

   npm install

   to add the Design System.

3. Run the application

   make run

Development

Get started with development by running the following commands. Before proceeding, make sure you have the development dependencies installed using the make install-dev command.

A Makefile is provided to simplify common development tasks. To view all available commands, run:

make

To run the UI in debug mode, you can add a root .env file, and add the setting FLASK_DEBUG=1.

ONS Design System

The ONS design system needs to be installed using npm. To install the ONS Design System npm package you will need to install node.js. To do this, use the following commands:

nvm install
nvm use

Then:

• Run npm install from the project root directory.

This will install the design system into a local node_modules folder. The @ons/design-system package is then automatically added to the jinja configuration.

The used design system version is pulled directly from the version in package.json. A fallback version is set in templates/base.html.

Run Application with Database and CIR FastAPI

To run the application with a local database and to point to CIR, you will need to complete the following steps:

• Clone the CIR FastAPI repository and follow their README to run the application. Note: The CIR application must be running for the UI to work as expected, so ensure you have completed this step before proceeding.

• Create or update a .env file to contain the following environment variables:

FIRESTORE_EMULATOR_HOST="localhost:8080"
CIR_API_BASE_URL="localhost:3030"

• To run the application locally with a Firestore emulator, use the following commands:

make dev-compose-up
make run

• Alternatively, you can use the following commands to run both the application and Firestore emulator with Docker:

docker-compose build
docker-compose up -d

Run All Tests

To run all functional and unit tests, run the following commands (Note: Functional tests require an instance of the Firestore Emulator and a local instance of CIR to be running):

make dev-compose-up

make test

Run Unit Tests with Coverage

The unit tests are written using the pytest framework. To run the tests and check coverage, run:

make test-unit

Run Functional Tests

The functional tests are written in Python using the Playwright framework. Functional tests require a running instance of the Firestore Emulator and CIR. To run the functional tests, use the following commands:

make dev-compose-up

make test-functional

Linting and Formatting

Various tools are used to lint and format the code in this project.

Python

The project uses Ruff, pylint and black for linting and formatting of the Python code.

The tools are configured using the pyproject.toml file.

To lint the Python code, run:

make lint

To auto-format the Python code, and correct fixable linting issues, run:

make format

MegaLinter (Lint/Format non-python files)

MegaLinter is utilised to lint the non-python files in the project. It offers a single interface to execute a suite of linters for multiple languages and formats, ensuring adherence to best practices and maintaining consistency across the repository without the need to install each linter individually.

MegaLinter examines various file types and tools, including GitHub Actions, Shell scripts, Dockerfile, etc. It is configured using the .mega-linter.yml file.

To run MegaLinter, ensure you have Docker installed on your system.

Note: The initial run may take some time to download the Docker image. However, subsequent executions will be considerably faster due to Docker caching. 🚀

To start the linter and automatically rectify fixable issues, run:

make megalint

Contributing

See CONTRIBUTING.md for details.

License

See LICENSE for details.