Compass/docs/development.md

Documentation for development

Warning

TODO: This document is a work in progress. Please help us improve it!

See those other useful documents as well:

• knowledge.md for high-level architecture and design decisions.
• README.md for the backend API
• README.md for the email routines and how to set up a local server for quick email rendering
• README.md for the frontend / web server

Adding a new profile field

A profile field is any variable associated with a user profile, such as age, politics, diet, etc. You may want to add a new profile field if it helps people find better matches.

To do so, you can add code in a similar way as in this commit for the religion field. If you also want people to filter by that profile field, you'll also need to add it to the search filters, as done in this commit (for the religion field as well).

Note that you will also need to add a column to the profiles table in the dev database before running the code; you can do so via this SQL command (change the type if not TEXT):

ALTER TABLE profiles ADD COLUMN profile_field TEXT;

Store it in add_profile_field.sql in the migrations folder and run migrate.sh from the root folder:

./scripts/migrate.sh backend/supabase/migrations/add_profile_field.sql

Then sync the database types from supabase to the local files (which assist Typescript in typing):

yarn regen-types dev

That's it!

Cover with tests

Best Practices

• Test Behavior, Not Implementation. Don’t test internal state or function calls unless you’re testing utilities or very critical behavior.
• Use msw to Mock APIs. Don't manually mock fetch—use msw to simulate realistic behavior, including network delays and errors.
• Don’t Overuse Snapshots. Snapshots are fragile and often meaningless unless used sparingly (e.g., for JSON response schemas).
• Prefer userEvent Over fireEvent. It simulates real user interactions more accurately.
• Avoid Testing Next.js Internals . You don’t need to test getStaticProps, getServerSideProps themselves—test what they render.
• Use jest.spyOn() for Internal Utilities . Avoid reaching into modules you don’t own.
• Don't test just for coverage. Test to prevent regressions, document intent, and handle edge cases.
• Don't write end-to-end tests for features that change frequently unless absolutely necessary.