The following document will explain how to configure your environment locally, run the app, and run the tests. This should help with meaningful contribution to the project and more reliable pull request approvals.
This project consists of two primary parts: a Vue.js frontend and a FastAPI backend.
There are two different package.json files which will need to have dependencies installed. You should install a modern version of node (14+) and the latest version of yarn v1 prior to running the following commands.
# double check node is installed
node --version
# double check yarn is installed
yarn --version
# install node packages to allow project-wide commit linting and other hooks
cd c:/git/sfm
yarn install # in the root directory
# install packages for the frontend
cd src/frontend
yarn installMake sure you have the following settings in your VSCode settings.json file to allow auto lint on save.
"editor.codeActionsOnSave": {
"source.fixAll": true,
}Prior to committing you'll also need to install pre-commit in your python environment which will enable the black fomatter for python. On each committhe pre-commit hooks will automatically:
- Format any python files with black
- Format any javascript or similar files with prettier
- lint any commit messages and enforce the commit standard outlined below.
This is the standard we use for commits: Commit Standard
git add xxx # stage your files
git commit -m "foo bar" # this will fail on auto-commit-lint
git commit -m "feat(foo): bar stuff & things" # this will pass
yarn commit # interactive commit messagesThe following are good examples of commit messages:
style(footer): remove blue border surrounding the right side text box
refactor(button props): change the button props to allow a text value to be passed in
We use standard version for our auto-changelog. It should be run after changes to the main branch usually by whoever accepts a pull request.
yarn release # after commiting, from the project rootClone the project from GitHub, perferably using ssh authentication with the following commands
# move to a folder called `git` <- not mandatory, but good practice
cd c:/git
# clone
git clone [email protected]:rropen/SFM.gitFor local development, the frontend just runs on your machine. After installing the dependencies in src/frontend you can run it with the commands below. This is the easiest way to work on this service.
You'll need to edit the two .env files and remove the example portion of the names leaving a .env and a .env.development. These files have some example environment variables. The default values should work fine for local development. This application has it's configuration values abstracted so as to run in multiple production environments. Without these files, your application won't be configured correctly.
# from the root/src/frontend folder
yarn serve # served with vite - app available at http://localhost:3000 by defaultyarn buildYou can run the E2E tests in one of two ways:
In a Terminal
# navigate to the frontend folder
cd /src/frontend
# run the command
yarn cyInteractively in a Browser
# navigate to the frontend folder
cd /src/frontend
# run the command
yarn cy-openYou can run the component tests in one of two ways:
In a Terminal
# navigate to the frontend folder
cd /src/frontend
# run the command
yarn cy-ctInteractively in a Browser
# navigate to the frontend folder
cd /src/frontend
# run the command
yarn cy-open-ctFor local development, the backend should be run in docker. You'll need to do one step before building the container. Make sure you install a version of Docker for your machine.
# Navigate to the backend service location
cd src/backend
# make a new .env file
cp .env.example .envThe example .env file should already be sufficient for local development with only the two environment variables. The .env file you use for your development shouldn't be committed to source code. This should be taken care of automatically by the .gitignore file.
# Move to the docker-compose context where the docker-compose files are located
cd src
# Build the container
docker-compose -f docker-compose.yml -f local-docker-compose.yml build
# Run the container in detached mode to return your command prompt
docker-compose -f docker-compose.yml -f local-docker-compose.yml up -dIf you want to install the dependencies and run the backend project locally for some reason, use pdm. PDM uses the pyproject.toml file to store the project requirements instead of the requirements.txt like most people are used to. It's actually a much nicer system that lets you avoid the virtual environment messes of the past. But it's a bit different and can take some getting used to.
You'll need python 3.8 or higher installed on your machine to use the packages as specified.
# verify you have pdm installed
pdm --version
# if you don't, install it
pip install pdm
cd src/backend
pdm installTo run the project just run pdm run uvicorn sfm.main:app --workers 4 --host 0.0.0.0 --port 8181 --reload
Your backend container should be running at http://localhost:8181/docs on your local machine.
To clear the database and prepare it for seeding mock data, simply navigate to the bottom of the SwaggerUI docs located at http://localhost:8181/docs and execute the /clear_local_db endpoint. To do this programmatically, send a DELETE request to http://localhost:8181/utilities/clear_local_db
To help with local development amongst teams, an API endpoint was created to initialize the database with a standardized set of mock data. This will require a cleared database to work. You can access this endpoint either at the bottom of the SwaggerUI docs located at http://localhost:8181/docs or by sending a POST request to http://localhost:8181/utilities/populate_mock_data
To run the backend unit tests:
# Move to the tests directory
cd src/backend/tests
# Run pytest
pdm run pytestNote: The command line options for pytest are configured in the pytest.ini file so you don't need to add them when running the command.
Code coverage will be displayed if all tests pass.