Contributor Guide

Thank you for your interest in improving this project. This project is open-source under the MIT license and welcomes contributions in the form of bug reports, feature requests, and pull requests.

Here is a list of important resources for contributors:

How to report a bug

Report bugs on the Issue Tracker.

When filing an issue, make sure to answer these questions:

  • Which operating system and Python version are you using?

  • Which version of this project are you using?

  • What did you do?

  • What did you expect to see?

  • What did you see instead?

The best way to get your bug fixed is to provide a test case, and/or steps to reproduce the issue.

How to request a feature

Request features on the Issue Tracker.

How to set up your development environment

You need Python 3.11+ and the following tools:

  • uv

  • Nox Install the package with development requirements:

$ uv sync --extra dev

How to test the project

Run the full test suite:

$ nox

List the available Nox sessions:

$ nox --list-sessions

You can also run a specific Nox session. For example, invoke the unit test suite like this:

$ nox --session=tests

Unit tests are located in example_project/test_*.py, and are written using the pytest testing framework.

Browser regression tests use Playwright. Run them with the dedicated Nox session:

$ uv run nox --session=tests-browser

You can pass extra pytest args and keep the browser test target:

$ uv run nox --session=tests-browser -- -q

If you want to run the browser subset directly, install Chromium and invoke pytest yourself:

$ PLAYWRIGHT_BROWSERS_PATH=/tmp/playwright-browsers uv run playwright install chromium
$ PLAYWRIGHT_BROWSERS_PATH=/tmp/playwright-browsers uv run pytest example_project/test_browser.py

JavaScript tests

JavaScript-side behavior is tested with Vitest in a JSDOM environment. The suite covers:

  • The inline script in src/django_tomselect/templates/django_tomselect/tomselect_setup.html (the window.djangoTomSelect API: initialize, destroy, prepareElement, fixAccessibilityClasses, cloneConfig, findSimilarConfig, cleanup).

  • The token query parser (client/plugins/token/parser.js) against the shared tests/fixtures/parser_corpus.json corpus that also drives Python tests in example_project/test_query_parser.py.

Install Node dependencies first (one-time):

$ npm install

Run the full JS test suite:

$ npm test

Watch mode during iteration:

$ npm run test:watch

Run a focused file:

$ npm test -- tests/js/regression/wrapper-hidden-accessible.test.js

Vitest tests live in tests/js/. The harness in tests/js/helpers/harness.js loads the inline script from tomselect_setup.html, strips its Django template tags, installs a TomSelect stub mirroring the real library, and injects the script into JSDOM. New JS files in tests/js/ and vitest.config.js should be linted explicitly with npx standard tests/js vitest.config.js - the packaged npm run lint script only covers client/.

How to submit changes

Open a pull request to submit changes to this project.

Your pull request needs to meet the following guidelines for acceptance:

  • The Nox test suite must pass without errors and warnings.

  • Include unit tests. This project maintains at least 80% code coverage.

  • If your changes add functionality, update the documentation accordingly.

Feel free to submit early, though - we can always iterate on this.

To run linting and code formatting checks before committing your change, you can install pre-commit as a Git hook by running the following command:

$ uv run nox --session=pre-commit -- install

It is recommended to open an issue before starting work on anything. This will allow a chance to talk it over with the owners and validate your approach.