Catty: The Reminders App

Catty is a small demo web app for tracking reminders. It uses:

• Python as the main programming language
• FastAPI for the backend
• HTMX 1.8.6 for handling dynamic interactions (instead of raw JavaScript)
• Jinja templates with HTML and CSS for the frontend
• TinyDB for the database
• Playwright and pytest for testing

Installing dependencies

You will need a recent version of Python to run this app. To install project dependencies:

pip install -r requirements.txt

It is recommended to install dependencies into a virtual environment.

Running the app

Prepare environment variables from template and export it:

cp .env.example .env
# Edit the .env file as needed
set -a; source .env; set +a

To run the app:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8181

Then, open your browser to http://127.0.0.1:8181 to load the app.

Logging into the app

The config.json file declares the users for the app. You may use any configured user credentials, or change them to your liking.

Setting the database path

The app uses TinyDB, which stores the database as a JSON file. The default database filepath is reminder_db.json. You may change this path in config.json. If you change the filepath, the app will automatically create a new, empty database.

Using the app

Catty is a reminders app. After you log in, you can create reminder lists.

Each reminder list appears on the left, and the items in the list appear on the right. You may add, delete, or edit lists and items. You may also strike out completed items.

Running tests

The app includes comprehensive tests using pytest and Playwright. Before running tests, make sure the app is running on http://127.0.0.1:8181.

First, install test dependencies if you haven't already:

pip install -r requirements.txt

Install Playwright browsers for UI testing:

playwright install --with-deps chromium

Then configure test settings in inputs.json:

{
  "base_url": "http://127.0.0.1:8181",
  "users": [
    {
      "username": "heisenberg",
      "password": "P@ssw0rd"
    },
    {
      "username": "tester", 
      "password": "foobar123"
    }
  ]
}

Run all tests:

python3 -m pytest

Run specific test types:

# Unit tests only
python3 -m pytest tests/test_unit.py

# API tests only  
python3 -m pytest tests/test_api.py

# UI tests only
python3 -m pytest -s -v --browser chromium tests/test_ui.py

Run tests with verbose output:

python3 -m pytest -v --browser chromium tests

Reading the docs

To read the API docs, open the following pages:

• /docs for classic OpenAPI docs
• /redoc for more modern ReDoc docs