From 34e8e2d7d242db1b4248b4cad6cf98049f691b43 Mon Sep 17 00:00:00 2001
From: Melissa DeLucchi <delucchi@andrew.cmu.edu>
Date: Thu, 23 Oct 2025 13:43:50 -0400
Subject: [PATCH] Document more than just timeout

---
 docs/practices/ci.rst                         |  2 +-
 docs/practices/overview.rst                   |  2 +-
 .../{pytest_timeout.rst => pytest_timing.rst} | 56 +++++++++++++++++--
 3 files changed, 54 insertions(+), 6 deletions(-)
 rename docs/practices/{pytest_timeout.rst => pytest_timing.rst} (56%)

diff --git a/docs/practices/ci.rst b/docs/practices/ci.rst
index e779fda..6ef854e 100644
--- a/docs/practices/ci.rst
+++ b/docs/practices/ci.rst
@@ -10,4 +10,4 @@ Continuous Integration
    ci_precommit
    code_coverage
    unit_testing
-   pytest_timeout
+   pytest_timing
diff --git a/docs/practices/overview.rst b/docs/practices/overview.rst
index 4267cf0..8d15ada 100644
--- a/docs/practices/overview.rst
+++ b/docs/practices/overview.rst
@@ -19,7 +19,7 @@ Practices
 * :doc:`precommit`
 * :doc:`pypi`
 * :doc:`sphinx`
-* :doc:`pytest_timeout`
+* :doc:`pytest_timing`
 
 Still have questions?
 --------------------------------
diff --git a/docs/practices/pytest_timeout.rst b/docs/practices/pytest_timing.rst
similarity index 56%
rename from docs/practices/pytest_timeout.rst
rename to docs/practices/pytest_timing.rst
index ea954e3..981b556 100644
--- a/docs/practices/pytest_timeout.rst
+++ b/docs/practices/pytest_timing.rst
@@ -1,3 +1,10 @@
+pytest timing
+||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+
+Slow unit tests can dis-incentivize writing or running unit tests. Luckily,
+there are many packages in the python ecosystem to help with this issue.
+This page lists some of the resources we find useful.
+
 pytest-timeout
 ===============================================================================
 
@@ -70,10 +77,10 @@ with the pytest annotation:
 
 Setting a timeout to 0 seconds disables the timeout entirely.
 
-Other fun things you can do
--------------------------------------------------------------------------------
+Find slow tests
+===============================================================================
 
-Even if you're not using this package, you can find slow-running tests in your
+Even if you're not using the timeout package, you can find slow-running tests in your
 suite with the ``--durations`` flag.
 
 .. code-block:: console
@@ -83,4 +90,45 @@ suite with the ``--durations`` flag.
 This will run your test suite as normal, outputting a list of the 10 slowest 
 calls after the execution. Note that this is not the 10 slowest **tests**: 
 the setup and teardown will be counted separately so put slow, shared fixture
-setup in a shared fixture!
\ No newline at end of file
+setup in a shared fixture!
+
+Profile slow tests
+===============================================================================
+
+pytest-profiling
+-------------------------------------------------------------------------------
+
+The `pytest-profiling <https://pypi.org/project/pytest-profiling/>`__ package
+is a plugin for pytest that will profile selected test cases, and optionally
+provide a heat map of where your tests are spending their time.
+
+.. code-block:: console
+
+    pip install pytest-profiling
+
+To get a list of the functions that your code is spending the most time in, just 
+pass the ``--profile`` argument to the pytest invocation. You can limit the test
+targets as you would with any other ``pytest`` execution using the ``-k <pattern>``
+argument. e.g. 
+
+.. code-block:: console
+
+    pytest --profile  -k test_cone_search_filters_correct_points
+    pytest --profile-svg  -k test_cone_search_filters_correct_points
+
+py-spy
+-------------------------------------------------------------------------------
+
+The `py-spy <https://github.com/benfred/py-spy>`__ package is a more general
+purpose sampling profiler for any python program. The python program you're 
+profiling is the ``pytest`` execution.
+
+Profiling the same target as above, using ``py-spy`` might look like:
+
+.. code-block:: console
+
+    py-spy record -o profile.svg -- pytest -k test_cone_search_filters_correct_points
+
+You will get a profiling flame chart saved to ``profile.svg``. These are not as
+easy to read as some other flame charts, but they're better than sifting through the
+raw results!
\ No newline at end of file