Cal-B/C

This tool calculates values based on Cal-B/C workbooks. It also provides automation around filling out workbooks.

Installation

Note

All commands below should be run inside this directory.

This application requires uv to be installed. This can be installed using asdf:

$ asdf plugin add uv
$ asdf install

Install dependencies using uv:

$ uv sync

Copy .env.example to .env and fill in the secret values in the .env file:

$ cp .env.example .env

Set your Google Cloud project and login:

$ gcloud config set project cal-itp-data-infra-staging # you will want to unset this later with `gcloud config unset project`
$ gcloud auth application-default login --login-config=iac/login.json --quiet

Create the database and run migrations:

$ uv run manage.py sqlcreate | psql
$ uv run manage.py migrate

Note

If you don't have postgresql, run brew install postgresql or visit https://www.postgresql.org/ for more information.

If you run into the error database "database_name" does not exist, you may need to create it manually running createdb <database_name>.

To check if your database was created, run psql -l.

In another terminal tab, start the Tailwind build process:

$ make tailwind

Then, start the Django server:

$ make start

Finally, start the Django tasks worker:

$ make worker

Now, visit the server at http://localhost:8000.

Linting

This project uses ruff to lint code. To run linting and apply fixes:

$ uv run ruff check --fix

Testing

In order to run tests, you will need to ensure that Playwright is installed:

$ uv run playwright install

Now, run the tests:

$ uv run manage.py test

Note

Remember to add new pages or components to /tests/cal_bc/system/test_accessibility_system.py.
Accessibility reports can be found locally in the axe-results/ folder.

Additional options you can add to the test command:

• To run only the web application tests, use:

  $ uv run manage.py test tests/cal_bc

• To run a specific file, add the file path. For example:

  $ uv run manage.py test tests/cal_bc/system/test_model_system.py

• To run a specific test, add the file path separating the test name with double colons ::. For example:

  $ uv run manage.py test tests/cal_bc/models/test_model.py::TestModel::test_version_has_form_link

If a Playwright test fails, you can find screenshots and videos locally in the cal-bc/test-results/ folder.

Playwright executes tests in a "headless" state, meaning it runs in the background without opening a user interface. If you want Playwright tests in a visible browser window use the -- --headed flag. You can change the velocity of the test adding --slowmo <milliseconds>.

For example:

$ uv run manage.py test tests/cal_bc/system/test_model_system.py -- --headed --slowmo 2000

VCR / Cassette files

If you are testing features that makes HTTP requests, you need to include the decorator @pytest.mark.vcr before your test definition. The Pytest VCR records your HTTP requests and responses into a cassette file so they can be replayed offline during future test runs. Cassette files are created inside cassettes\ folder located in the same folder as your test file.

To run for the first time, or if you deleted the cassette file, add -- --record-mode=once after the test command. For example:

$ uv run manage.py test tests/cal_bc/system/test_accessibility_system.py -- --record-mode=once

To update a cassette file add -- --record-mode=rewrite after the test command. For example:

$ uv run manage.py test tests/cal_bc/system/test_project_system.py  -- --record-mode=rewrite

Managing Django in Cloud Run

To run manage.py commands on the deployed Cloud Run instance, use the cal-bc-staging-manage Cloud Run Job.

For example, if you want to migrate the models app back to a specific migration, you would locally run:

$ uv run manage.py migrate models 0013_subsection_description

The Cloud Run Jobs equivalent using cal-bc-staging-manage is:

$ gcloud run jobs execute cal-bc-staging-manage --args migrate,models,0013_subsection_description --wait

Administering the site locally

In order to access the admin site at http://localhost:8000/admin, you need to create a superuser for your DOT login:

$ uv run manage.py createsuperuser
Username (leave blank to use 'yourname'): Your.Name@dot.ca.gov
Email address: Your.Name@dot.ca.gov
Password: ********
Password (again): ********

Now, when you visit the admin site, you can log in with your DOT account as usual.

Note

If you forget to add your user before this point, the Azure Entra ID login package will automatically add a user and disallow access. You will need to either manually make your user a superuser or delete your user account.

To access or make changes to your local database, run:

$ uv run manage.py dbshell

To reset your local database, run:

$ uv run manage.py reset_db

You can seed your local database with a basic sketch model with uv run manage.py seed. You can clear all model and associated data with uv run manage.py clear_models.

License

This tool is licensed under the terms of the GNU Affero General Public License.