pytest-memray#

A pytest plugin for easy integration of memray in your test suite. It can produce reports like:

$ pytest --memray /w/demo 
=================================== test session starts ====================================
platform linux -- Python 3.10.4, pytest-7.1.2, pluggy-1.0.0
rootdir: /w
plugins: memray-1.3.0
collected 2 items

demo/test_ok.py .M                                                                   [100%]

========================================= FAILURES =========================================
____________________________________ test_memory_exceed ____________________________________
Test was limited to 100.0KiB but allocated 117.2KiB
------------------------------------ memray-max-memory -------------------------------------
Test is using 117.2KiB out of limit of 100.0KiB
List of allocations: 
	- <listcomp>:/w/demo/test_ok.py:17 -> 117.2KiB

====================================== MEMRAY REPORT =======================================
Allocations results for demo/test_ok.py::test_memory_exceed

	 📦 Total memory allocated: 117.2KiB
	 📏 Total allocations: 30
	 📊 Histogram of allocation sizes: |█|
	 🥇 Biggest allocating functions:
		- <listcomp>:/w/demo/test_ok.py:17 -> 117.2KiB


Allocations results for demo/test_ok.py::test_track

	 📦 Total memory allocated: 58.4KiB
	 📏 Total allocations: 63
	 📊 Histogram of allocation sizes: |█ ▄ █    |
	 🥇 Biggest allocating functions:
		- test_track:/w/demo/test_ok.py:12 -> 39.1KiB
		- _compile_bytecode:<frozen importlib._bootstrap_external>:672 -> 7.2KiB
		- _call_with_frames_removed:<frozen importlib._bootstrap>:241 -> 4.7KiB
		- _is_marked_for_rewrite:/v/lib/python3.10/site-packages/_pytest/assertion/rewrite.py:240 -> 4.5KiB
		- _call_with_frames_removed:<frozen importlib._bootstrap>:241 -> 1.8KiB


================================= short test summary info ==================================
MEMORY PROBLEMS demo/test_ok.py::test_memory_exceed
=============================== 1 failed, 1 passed in 0.03s ================================

Usage#

Installation#

This plugin can be installed using pip:

pip install pytest-memray

pytest-memray is a pytest plugin. It is enabled when you pass --memray to pytest:

pytest tests/ --memray

Allocation tracking#

By default, the plugin will track allocations in all tests. This information is reported after tests run ends:

$ pytest --memray /w/demo 
=================================== test session starts ====================================
platform linux -- Python 3.10.4, pytest-7.1.2, pluggy-1.0.0
rootdir: /w
plugins: memray-1.3.0
collected 2 items

demo/test_ok.py .M                                                                   [100%]

========================================= FAILURES =========================================
____________________________________ test_memory_exceed ____________________________________
Test was limited to 100.0KiB but allocated 117.2KiB
------------------------------------ memray-max-memory -------------------------------------
Test is using 117.2KiB out of limit of 100.0KiB
List of allocations: 
	- <listcomp>:/w/demo/test_ok.py:17 -> 117.2KiB

====================================== MEMRAY REPORT =======================================
Allocations results for demo/test_ok.py::test_memory_exceed

	 📦 Total memory allocated: 117.2KiB
	 📏 Total allocations: 30
	 📊 Histogram of allocation sizes: |█|
	 🥇 Biggest allocating functions:
		- <listcomp>:/w/demo/test_ok.py:17 -> 117.2KiB


Allocations results for demo/test_ok.py::test_track

	 📦 Total memory allocated: 58.4KiB
	 📏 Total allocations: 63
	 📊 Histogram of allocation sizes: |█ ▄ █    |
	 🥇 Biggest allocating functions:
		- test_track:/w/demo/test_ok.py:12 -> 39.1KiB
		- _compile_bytecode:<frozen importlib._bootstrap_external>:672 -> 7.2KiB
		- _call_with_frames_removed:<frozen importlib._bootstrap>:241 -> 4.7KiB
		- _is_marked_for_rewrite:/v/lib/python3.10/site-packages/_pytest/assertion/rewrite.py:240 -> 4.5KiB
		- _call_with_frames_removed:<frozen importlib._bootstrap>:241 -> 1.8KiB


================================= short test summary info ==================================
MEMORY PROBLEMS demo/test_ok.py::test_memory_exceed
=============================== 1 failed, 1 passed in 0.03s ================================

Markers#

This plugin provides markers that can be used to enforce additional checks and validations on tests when this plugin is enabled.

Important

These markers do nothing when the plugin is not enabled.

`limit_memory`#

When this marker is applied to a test, it will cause the test to fail if the execution of the test allocates more memory than allowed. It takes a single argument with a string indicating the maximum memory that the test can allocate.

The format for the string is <NUMBER> ([KMGTP]B|B). The marker will raise ValueError if the string format cannot be parsed correctly.

Warning

As the Python interpreter has its own object allocator is possible that memory is not immediately released to the system when objects are deleted, so tests using this marker may need to give some room to account for this.

Example of usage:

@pytest.mark.limit_memory("24 MB")
def test_foobar():
    pass # do some stuff that allocates memory

Configuration#

This plugin provides a clean minimal set of command line options that are added to pytest. The complete list of command line options is:

Command line options

--memray: Activate memray tracking.
--most-allocations=MOST_ALLOCATIONS: Show the N tests that allocate most memory (N=0 for all).
--hide-memray-summary: Hide the memray summary at the end of the execution.
--memray-bin-path: Path where to write the memray binary dumps (by default a temporary folder).
--memray-bin-prefix: Prefix to use for the binary dump (by default a random UUID4 hex)

Config file options

memray(bool): Activate memray tracking.
most-allocations(string): Show the N tests that allocate most memory (N=0 for all).
hide_memray_summary(bool): Hide the memray summary at the end of the execution.

Release History#

v1.3.0 (2022-08-21)#

Features - 1.3.0#

Ensure Python 3.11 support - by @gaborbernat. (#18)

v1.2.0 (2022-05-26)#

Features - 1.2.0#

Allow specifying the prefix used for -memray-bin-path dumps via the -memray-bin-prefix (and if specified and file already exists will be recreated) - by @gaborbernat. (#28)

Improved Documentation - 1.2.0#

Fix documentation links to point from Gitub Pages to readthedocs.org - by @gaborbernat. (#12)
Update examples in configuration and add -memray-bin-path - by @gaborbernat. (#26)
Fix minimum python version in documentation from 3.7 to 3.8 - by @ChaoticRoman. (#30)

v1.1.0 (2022-05-17)#

Features - 1.1.0#

Report memory limit and allocated memory in longrepr - by @petr-tik. (#5)
Allow passing --memray-bin-path argument to the CLI to allow persisting the binary dumps - by @gaborbernat. (#10)
Release a pure python wheel - by @gaborbernat. (#11)
Switch build backend from setuptools to hatchling - by @gaborbernat. (#12)

Bug Fixes - 1.1.0#

Causes built-in junit-xml results writer to fail - by @petr-tik. (#3)

Improved Documentation - 1.1.0#

Move documentation from Github Pages to readthedocs - by @gaborbernat. (#20)

v1.0.0 (2022-04-09)#

Initial release.

pytest-memray#

Usage#

Installation#

Allocation tracking#

Markers#

limit_memory#

Configuration#

Release History#

v1.3.0 (2022-08-21)#

Features - 1.3.0#

v1.2.0 (2022-05-26)#

Features - 1.2.0#

Improved Documentation - 1.2.0#

v1.1.0 (2022-05-17)#

Features - 1.1.0#

Bug Fixes - 1.1.0#

Improved Documentation - 1.1.0#

v1.0.0 (2022-04-09)#

`limit_memory`#