Skip to content

BOTS.md

Latest commit

 

History

History
55 lines (36 loc) · 2.49 KB

BOTS.md

File metadata and controls

55 lines (36 loc) · 2.49 KB
Raw

Notes for AI Assistants

Development Environment

The Python virtual environment is likely located at ./venv, but this is just a guess - the user may have it elsewhere or may have already activated a virtualenv. If commands like python or pytest work directly, the environment is probably already active.

If you need to use the venv explicitly:

./venv/bin/python -m pytest src/toil/test/path/to/test.py -v
./venv/bin/python -c "import toil; print(toil.__version__)"

Running Tests

Tests use pytest. Example commands:

# Run a specific test file
./venv/bin/python -m pytest src/toil/test/server/safeFileTest.py -v

# Run a specific test
./venv/bin/python -m pytest src/toil/test/server/safeFileTest.py::TestSafeFileInterleaving::test_reader_blocked_while_writer_holds_lock -v

# Run tests with a keyword filter
./venv/bin/python -m pytest src/toil/test -k "safe" -v

Running Make Targets (mypy, tests, etc.)

The Makefile targets require the virtualenv to be activated. Some targets (like test_debug) enforce this with a check_venv guard that checks for VIRTUAL_ENV in the environment. Set PATH and VIRTUAL_ENV to satisfy this without needing source:

PATH="./venv/bin:$PATH" VIRTUAL_ENV=./venv make mypy
PATH="./venv/bin:$PATH" VIRTUAL_ENV=./venv make test_debug tests='src/toil/test/path/to/test.py::TestClass::test_name'

Running Individual WDL Spec Unit Tests

The WDL spec embeds example workflows as unit tests (under the wdl-1.1 and wdl-1.2 branches of https://github.com/openwdl/wdl). TestWDLConformance.test_single_unit_test in src/toil/test/wdl/wdltoil_test.py runs one such test at a time and is controlled by environment variables:

  • WDL_UNIT_TEST_ID: which test to run (default: glob_task)
  • WDL_UNIT_TEST_VERSION: WDL version (default: 1.1)
WDL_UNIT_TEST_ID=serde_pair ./venv/bin/python -m pytest \
  src/toil/test/wdl/wdltoil_test.py::TestWDLConformance::test_single_unit_test \
  --timeout=300 -v -s

This test clones remote git repos and may be slow. Many WDL spec tasks run inside containers, so Docker must be running — if the test fails with a Docker connection error, ask the user to start Docker before retrying.

Code Style

Docstrings state the contract (what, not how). Implementation strategy goes in comments on the relevant code. Explain a concept once in a canonical docstring; reference it elsewhere. Names must be precise: no redundant qualifiers, invented terms, overclaiming, or test content as examples.