# Django Mercury ๐
[](https://badge.fury.io/py/django-mercury-performance)
[](https://www.python.org/downloads/)
[](https://docs.djangoproject.com/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/ibrahim-sisar/EduLite)
[](https://github.com/80-20-Human-In-The-Loop)
**Part of the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) ecosystem**
> Test Django app speed. Learn why it's slow. Fix it.
## ๐ Quick Install
```bash
pip install django-mercury-performance
```
Then in your test files:
```python
from django_mercury import DjangoMercuryAPITestCase
class MyPerformanceTest(DjangoMercuryAPITestCase):
def test_api_performance(self):
response = self.client.get('/api/endpoint/')
# Performance is automatically monitored and reported!
```
## ๐ Origin Story
Mercury started at [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn with slow internet. We found our UserSearchView made **825 database queries** to show one page!
We built Mercury to find these problems and teach you how to fix them. Mercury follows EduLite's values: **Fair**, **Free**, and **Open**. Everyone can use it and learn.
## ๐ฏ Current Status: v0.0.2 on PyPI! ๐
**What Works Now:**
- โ
**Install from PyPI** - `pip install django-mercury-performance`
- โ
Finds N+1 query problems
- โ
Grades speed (F to A+)
- โ
Two test types: `DjangoMercuryAPITestCase` and `DjangoPerformanceAPITestCase`
- โ
Knows what type of code runs
- โ
Teaches when tests fail
- โ
Fast C code for speed
- โ
Tracks time, queries, and memory
**What We Actually Found:**
```text
๐จ POTENTIAL N+1 QUERY PROBLEM! ๐จ
Severity: CRITICAL (825 queries)
```
**Coming Soon:**
- ๐ AI help to fix slow code
- ๐ Track speed over time
- ๐ Test all view types
- ๐ Find when code gets slower
- ๐ Better test support
## ๐ฆ Installation
### Install from PyPI (Recommended)
```bash
pip install django-mercury-performance
```
### Install from Source
```bash
# Clone the repository
git clone https://github.com/Django-Mercury/Performance-Testing.git
cd Django-Mercury-Performance-Testing
# Install in development mode
pip install -e .
# If you want to modify the C extensions
cd django_mercury/c_core
make clean && make
```
## ๐ Quick Start
### Two Ways to Test Performance
Choose the test class that fits your needs.
#### 1. DjangoMercuryAPITestCase - Automatic Testing
Mercury watches your tests automatically. You write normal tests. Mercury finds problems.
```python
from django_mercury import DjangoMercuryAPITestCase
class UserSearchPerformanceTest(DjangoMercuryAPITestCase):
"""Mercury monitors every test automatically."""
def test_user_search(self):
# Write your normal test
response = self.client.get('/api/users/search/?q=test')
self.assertEqual(response.status_code, 200)
# Mercury checks performance automatically
```
**What Mercury does:**
- Counts database queries
- Measures response time
- Tracks memory usage
- Finds N+1 problems
- Shows clear reports
#### 2. DjangoPerformanceAPITestCase - Manual Control
You control when to monitor. Good for specific performance checks.
```python
from django_mercury import DjangoPerformanceAPITestCase
from django_mercury import monitor_django_view
class AdvancedPerformanceTest(DjangoPerformanceAPITestCase):
"""Control exactly what you test."""
def test_with_assertions(self):
with monitor_django_view("search") as monitor:
response = self.client.get('/api/users/search/')
# Check specific limits
self.assertResponseTimeLess(monitor, 100) # Under 100ms
self.assertQueriesLess(monitor, 10) # Under 10 queries
self.assertNoNPlusOne(monitor) # No N+1 problems
```
**You control:**
- When monitoring starts
- What to check
- Your performance limits
## ๐ Real Output from Mercury
This is actual output from testing EduLite:
```text
๐จ MERCURY PERFORMANCE DASHBOARD - UserSearchPerformanceTest
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ ๐ Overall Status: NEEDS IMPROVEMENT โ
โ ๐ Overall Grade: F (20.5/100) โ
โ ๐ Tests Executed: 12 โ
โ โฑ๏ธ Avg Response Time: 105.6ms โ
โ ๐ง Avg Memory Usage: 91.7MB โ
โ ๐๏ธ Total Queries: 2761 (230.1 avg) โ
โ ๐จ N+1 Issues: 10/12 tests affected โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
```
## ๐ How Mercury Works
Mercury follows the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop/Community) way:
**80% Computer Help:**
- Watches performance automatically
- Finds N+1 problems
- Grades your code speed
- Manages limits
**20% Human Control:**
- You understand WHY speed matters
- You choose how to fix problems
- You learn from the guides
- You make design choices
**Example: How Mercury Teaches**
When a test fails, Mercury helps you learn:
```text
๐ MERCURY EDUCATIONAL GUIDANCE
============================================================
๐ฏ Test: test_user_list_view
โ ๏ธ Default thresholds exceeded
๐๏ธ Query Count: 230 (limit: 10)
โ 220 extra queries (2200% exceeded)
๐ก SOLUTION: N+1 Query Pattern Detected
Your code is likely missing select_related() or prefetch_related()
Try: User.objects.select_related('profile').prefetch_related('groups')
๐ ๏ธ Quick Fix for Testing:
cls.set_performance_thresholds({'query_count_max': 250})
But the REAL fix is optimizing your queries!
============================================================
```
## ๐ ๏ธ Performance Checks
### Test Methods You Can Use
```python
# Check response time
self.assertResponseTimeLess(monitor, 100) # Must be under 100ms
self.assertPerformanceFast(monitor) # Must be fast
self.assertPerformanceNotSlow(monitor) # Must not be slow
# Check database queries
self.assertQueriesLess(monitor, 10) # Must use less than 10 queries
self.assertNoNPlusOne(monitor) # Must not have N+1 problems
# Check memory use
self.assertMemoryLess(monitor, 50) # Must use less than 50MB
self.assertMemoryEfficient(monitor) # Must use memory well
# Check cache use
self.assertGoodCachePerformance(monitor, 0.8) # Must hit cache 80% of time
```
## ๐ง Setup Options
```python
class MyTest(DjangoMercuryAPITestCase):
@classmethod
def setUpClass(cls):
super().setUpClass()
# Turn Mercury features on or off
cls.configure_mercury(
enabled=True, # Turn on Mercury
auto_scoring=True, # Grade tests automatically
verbose_reporting=False, # Show less detail
educational_guidance=True # Show help messages
)
# Set your speed limits
cls.set_performance_thresholds({
'response_time_ms': 100, # Max time: 100ms
'query_count_max': 10, # Max queries: 10
'memory_overhead_mb': 20, # Max extra memory: 20MB
})
```
## ๐งช Testing Django Mercury
We provide two test runners to help you test the framework.
### What Our Tests Do
Tests make sure Django Mercury works correctly. They check:
- Python code works as expected
- C extensions compile and run fast
- Performance monitoring catches problems
- Everything works together
### Two Test Runners
#### 1. Python Test Runner: `test_runner.py`
Tests all Python code with performance timing.
**Features:**
- Shows test speed with colors (๐ข fast, ๐ก medium, ๐ด slow, ๐ very slow)
- Coverage reports (how much code is tested)
- Finds slow tests automatically
- Groups results by module
#### 2. C Test Runner: `c_test_runner.sh`
Tests all C extensions for speed and correctness.
**Features:**
- Builds C libraries
- Runs unit tests
- Checks memory safety
- Generates coverage reports
### How to Run Tests
#### Quick Start (Test Everything)
```bash
# Test Python code
python test_runner.py
# Test C code
./c_test_runner.sh test
```
#### Detailed Testing
```bash
# Python tests with coverage report
python test_runner.py --coverage --verbose
# C tests with coverage analysis
./c_test_runner.sh coverage
# Test everything
python test_runner.py --all
./c_test_runner.sh all
```
### Understanding Test Output
#### Python Test Colors
Your tests show timing with colors:
| Color | Time | Meaning |
|-------|------|---------|
| ๐ข Green | <0.1s | Fast - Great! |
| ๐ก Yellow | 0.1-0.5s | Medium - OK |
| ๐ด Red | 0.5-2s | Slow - Needs work |
| ๐ Purple | >2s | Very slow - Problem! |
#### Example Output
```
๐ Starting Timed Test Run
==================================================
Legend: ๐ข <0.1s | ๐ก 0.1-0.5s | ๐ด >0.5s | ๐ >2s
==================================================
๐ Running: tests.monitor.test_django_base ... ๐ข 0.045s โ
๐ Running: tests.monitor.test_metrics ... ๐ก 0.234s โ
๐ Running: tests.integration.test_api ... ๐ด 0.678s โ
๐ PERFORMANCE SUMMARY
Total time: 0.957s
Average per test: 0.319s
```
### Common Testing Tasks
#### Run Specific Tests
```bash
# Test only monitor module
python test_runner.py --module monitor
# List all test modules
python test_runner.py --list-modules
```
#### Build and Clean
```bash
# Clean everything
./c_test_runner.sh clean
# Rebuild C libraries
./c_test_runner.sh build
# Run benchmarks
./c_test_runner.sh benchmark
```
#### Before You Commit
Always run these commands:
```bash
# 1. Check Python tests pass
python test_runner.py
# 2. Check C tests pass
./c_test_runner.sh test
# 3. Check code style
black django_mercury/
ruff check django_mercury/
```
### Adding Your Own Tests
#### Python Tests
Create a file in `tests/` directory:
```python
# tests/test_my_feature.py
import unittest
from django_mercury import DjangoMercuryAPITestCase
class TestMyFeature(DjangoMercuryAPITestCase):
def test_feature_works(self):
# Your test here
response = self.client.get('/api/test/')
self.assertEqual(response.status_code, 200)
```
#### C Tests
Create a file in `django_mercury/c_core/tests/`:
```c
// simple_test_myfeature.c
#include <stdio.h>
#include <assert.h>
int main() {
printf("Testing my feature...\n");
// Your test here
assert(1 == 1);
printf("โ
Test passed!\n");
return 0;
}
```
### Getting Help
- **Test failures?** Check the error message first
- **Slow tests?** Look for `time.sleep()` or database queries
- **C compilation errors?** Run `./c_test_runner.sh clean` then `build`
- **Still stuck?** Open an issue with your test output
## ๐ฏ Real Results at EduLite
Before Mercury:
- UserSearchView used **825 queries** to show one page
- We could not see speed problems
- Students with slow internet could not use the app
After Mercury:
- Found the exact problem
- Fixed it to use only **12 queries**
- Now we check speed on every code change
## ๐ง Future Plans
### Phase 1: First Release โ
- โ
Watch performance
- โ
Find N+1 problems
- โ
Show helpful guides
- โ
Available on PyPI
### Phase 2: Make It Better
- ๐ Fix test problems
- ๐ Support all view types
- ๐ Track speed over time
- ๐ Find when code gets slower
- ๐ Better guides and examples
### Phase 3: Add AI Help
- ๐ AI suggests fixes
- ๐ Create fixes you can review
- ๐ Help new developers learn
- ๐ Let you add custom checks
## ๐ค Contributing
Mercury is part of [EduLite](https://github.com/ibrahim-sisar/EduLite) and [Human in the Loop](https://github.com/80-20-Human-In-The-Loop). We welcome everyone.
### Our Values
- **Education First**: Tools should teach, not just find problems
- **Human Understanding**: You control your code
- **Open Source**: Built together, shared with everyone
### How You Can Help
1. **Test Mercury** - Try it on your Django project
2. **Report Problems** - Tell us what doesn't work
3. **Share Ideas** - Suggest improvements
4. **Write Code** - Fix bugs or add features
5. **Improve Docs** - Make them clearer
6. **Help Others** - Answer questions
### Getting Started
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
**New to open source?** Start here:
- Look for "good first issue" labels
- Ask questions - we're here to help
- Small fixes matter too
## ๐ซ Made for Learning
Mercury was made for [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn even with slow internet. Mercury helps by:
- Working on slow computers
- Teaching as it tests
- Helping developers learn
- Making apps work for everyone
## ๐ License
This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
### Why GPL-3.0?
We use GPL-3.0 because it matches our values:
- **๐ Open**: Code stays open for everyone
- **๐ Free**: You can use, study, share, and improve it
- **โ๏ธ Fair**: Improvements must be shared
- **๐ค Copyleft**: Stays free forever
If you share a changed version, you must:
- Share your code
- Use GPL-3.0 license
- Keep all notices
- List your changes
This keeps knowledge open for all.
For the full license text, see [LICENSE](LICENSE) or visit [GNU GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.html).
## ๐ Thanks To
- [EduLite Team](https://github.com/ibrahim-sisar/EduLite) - For showing us the need
- [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) - For the ideas
- Django/DRF Community - For the tools
---
**Mercury**: Making performance testing simple for everyone.
*Built with โค๏ธ by developers who believe people should understand their code.*
Raw data
{
"_id": null,
"home_page": "https://github.com/Django-Mercury/Performance-Testing",
"name": "django-mercury-performance",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Mathew Storm <mathewstormdev@gmail.com>",
"keywords": "django, performance, testing, monitoring, optimization, n+1, queries, profiling, mercury, rest-framework, api, benchmarking",
"author": "Django Mercury Team",
"author_email": "Django Mercury Team <mathewstormdev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/e1/933212934ab0d3a20a7ea0ec303760a20d8e58230183b4fa9a9b0288bddb/django_mercury_performance-0.0.2.tar.gz",
"platform": null,
"description": "# Django Mercury \ud83d\ude80\n\n[](https://badge.fury.io/py/django-mercury-performance)\n[](https://www.python.org/downloads/)\n[](https://docs.djangoproject.com/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://github.com/ibrahim-sisar/EduLite)\n[](https://github.com/80-20-Human-In-The-Loop)\n\n**Part of the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) ecosystem**\n\n> Test Django app speed. Learn why it's slow. Fix it.\n\n## \ud83d\ude80 Quick Install\n\n```bash\npip install django-mercury-performance\n```\n\nThen in your test files:\n```python\nfrom django_mercury import DjangoMercuryAPITestCase\n\nclass MyPerformanceTest(DjangoMercuryAPITestCase):\n def test_api_performance(self):\n response = self.client.get('/api/endpoint/')\n # Performance is automatically monitored and reported!\n```\n\n## \ud83c\udf1f Origin Story\n\nMercury started at [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn with slow internet. We found our UserSearchView made **825 database queries** to show one page!\n\nWe built Mercury to find these problems and teach you how to fix them. Mercury follows EduLite's values: **Fair**, **Free**, and **Open**. Everyone can use it and learn.\n\n## \ud83c\udfaf Current Status: v0.0.2 on PyPI! \ud83c\udf89\n\n**What Works Now:**\n- \u2705 **Install from PyPI** - `pip install django-mercury-performance`\n- \u2705 Finds N+1 query problems\n- \u2705 Grades speed (F to A+) \n- \u2705 Two test types: `DjangoMercuryAPITestCase` and `DjangoPerformanceAPITestCase`\n- \u2705 Knows what type of code runs\n- \u2705 Teaches when tests fail\n- \u2705 Fast C code for speed\n- \u2705 Tracks time, queries, and memory\n\n**What We Actually Found:**\n```text\n\ud83d\udea8 POTENTIAL N+1 QUERY PROBLEM! \ud83d\udea8\nSeverity: CRITICAL (825 queries)\n```\n\n**Coming Soon:**\n- \ud83d\udd1c AI help to fix slow code\n- \ud83d\udd1c Track speed over time\n- \ud83d\udd1c Test all view types\n- \ud83d\udd1c Find when code gets slower\n- \ud83d\udd1c Better test support\n\n## \ud83d\udce6 Installation\n\n### Install from PyPI (Recommended)\n\n```bash\npip install django-mercury-performance\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/Django-Mercury/Performance-Testing.git\ncd Django-Mercury-Performance-Testing\n\n# Install in development mode\npip install -e .\n\n# If you want to modify the C extensions\ncd django_mercury/c_core\nmake clean && make\n```\n\n## \ud83d\ude80 Quick Start\n\n### Two Ways to Test Performance\n\nChoose the test class that fits your needs.\n\n#### 1. DjangoMercuryAPITestCase - Automatic Testing\n\nMercury watches your tests automatically. You write normal tests. Mercury finds problems.\n\n```python\nfrom django_mercury import DjangoMercuryAPITestCase\n\nclass UserSearchPerformanceTest(DjangoMercuryAPITestCase):\n \"\"\"Mercury monitors every test automatically.\"\"\"\n \n def test_user_search(self):\n # Write your normal test\n response = self.client.get('/api/users/search/?q=test')\n self.assertEqual(response.status_code, 200)\n # Mercury checks performance automatically\n```\n\n**What Mercury does:**\n- Counts database queries\n- Measures response time \n- Tracks memory usage\n- Finds N+1 problems\n- Shows clear reports\n\n#### 2. DjangoPerformanceAPITestCase - Manual Control\n\nYou control when to monitor. Good for specific performance checks.\n\n```python\nfrom django_mercury import DjangoPerformanceAPITestCase\nfrom django_mercury import monitor_django_view\n\nclass AdvancedPerformanceTest(DjangoPerformanceAPITestCase):\n \"\"\"Control exactly what you test.\"\"\"\n \n def test_with_assertions(self):\n with monitor_django_view(\"search\") as monitor:\n response = self.client.get('/api/users/search/')\n \n # Check specific limits\n self.assertResponseTimeLess(monitor, 100) # Under 100ms\n self.assertQueriesLess(monitor, 10) # Under 10 queries\n self.assertNoNPlusOne(monitor) # No N+1 problems\n```\n\n**You control:**\n- When monitoring starts\n- What to check\n- Your performance limits\n\n## \ud83d\udcca Real Output from Mercury\n\nThis is actual output from testing EduLite:\n\n```text\n\ud83c\udfa8 MERCURY PERFORMANCE DASHBOARD - UserSearchPerformanceTest\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \ud83d\ude80 Overall Status: NEEDS IMPROVEMENT \u2502\n\u2502 \ud83c\udf93 Overall Grade: F (20.5/100) \u2502\n\u2502 \ud83d\udcca Tests Executed: 12 \u2502\n\u2502 \u23f1\ufe0f Avg Response Time: 105.6ms \u2502\n\u2502 \ud83e\udde0 Avg Memory Usage: 91.7MB \u2502\n\u2502 \ud83d\uddc3\ufe0f Total Queries: 2761 (230.1 avg) \u2502\n\u2502 \ud83d\udea8 N+1 Issues: 10/12 tests affected \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n## \ud83c\udf93 How Mercury Works\n\nMercury follows the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop/Community) way:\n\n**80% Computer Help:**\n- Watches performance automatically\n- Finds N+1 problems\n- Grades your code speed\n- Manages limits\n\n**20% Human Control:**\n- You understand WHY speed matters\n- You choose how to fix problems\n- You learn from the guides\n- You make design choices\n\n**Example: How Mercury Teaches**\n\nWhen a test fails, Mercury helps you learn:\n\n```text\n\ud83d\udcda MERCURY EDUCATIONAL GUIDANCE\n============================================================\n\ud83c\udfaf Test: test_user_list_view\n\u26a0\ufe0f Default thresholds exceeded\n\n\ud83d\uddc3\ufe0f Query Count: 230 (limit: 10)\n \u2192 220 extra queries (2200% exceeded)\n\n\ud83d\udca1 SOLUTION: N+1 Query Pattern Detected\n Your code is likely missing select_related() or prefetch_related()\n \n Try: User.objects.select_related('profile').prefetch_related('groups')\n\n\ud83d\udee0\ufe0f Quick Fix for Testing:\n cls.set_performance_thresholds({'query_count_max': 250})\n \n But the REAL fix is optimizing your queries!\n============================================================\n```\n\n## \ud83d\udee0\ufe0f Performance Checks\n\n### Test Methods You Can Use\n\n```python\n# Check response time\nself.assertResponseTimeLess(monitor, 100) # Must be under 100ms\nself.assertPerformanceFast(monitor) # Must be fast\nself.assertPerformanceNotSlow(monitor) # Must not be slow\n\n# Check database queries \nself.assertQueriesLess(monitor, 10) # Must use less than 10 queries\nself.assertNoNPlusOne(monitor) # Must not have N+1 problems\n\n# Check memory use\nself.assertMemoryLess(monitor, 50) # Must use less than 50MB\nself.assertMemoryEfficient(monitor) # Must use memory well\n\n# Check cache use\nself.assertGoodCachePerformance(monitor, 0.8) # Must hit cache 80% of time\n```\n\n## \ud83d\udd27 Setup Options\n\n```python\nclass MyTest(DjangoMercuryAPITestCase):\n @classmethod\n def setUpClass(cls):\n super().setUpClass()\n \n # Turn Mercury features on or off\n cls.configure_mercury(\n enabled=True, # Turn on Mercury\n auto_scoring=True, # Grade tests automatically\n verbose_reporting=False, # Show less detail\n educational_guidance=True # Show help messages\n )\n \n # Set your speed limits\n cls.set_performance_thresholds({\n 'response_time_ms': 100, # Max time: 100ms\n 'query_count_max': 10, # Max queries: 10\n 'memory_overhead_mb': 20, # Max extra memory: 20MB\n })\n```\n\n## \ud83e\uddea Testing Django Mercury\n\nWe provide two test runners to help you test the framework.\n\n### What Our Tests Do\n\nTests make sure Django Mercury works correctly. They check:\n- Python code works as expected\n- C extensions compile and run fast\n- Performance monitoring catches problems\n- Everything works together\n\n### Two Test Runners\n\n#### 1. Python Test Runner: `test_runner.py`\n\nTests all Python code with performance timing.\n\n**Features:**\n- Shows test speed with colors (\ud83d\udfe2 fast, \ud83d\udfe1 medium, \ud83d\udd34 slow, \ud83d\udc80 very slow)\n- Coverage reports (how much code is tested)\n- Finds slow tests automatically\n- Groups results by module\n\n#### 2. C Test Runner: `c_test_runner.sh` \n\nTests all C extensions for speed and correctness.\n\n**Features:**\n- Builds C libraries\n- Runs unit tests\n- Checks memory safety\n- Generates coverage reports\n\n### How to Run Tests\n\n#### Quick Start (Test Everything)\n\n```bash\n# Test Python code\npython test_runner.py\n\n# Test C code \n./c_test_runner.sh test\n```\n\n#### Detailed Testing\n\n```bash\n# Python tests with coverage report\npython test_runner.py --coverage --verbose\n\n# C tests with coverage analysis\n./c_test_runner.sh coverage\n\n# Test everything\npython test_runner.py --all\n./c_test_runner.sh all\n```\n\n### Understanding Test Output\n\n#### Python Test Colors\n\nYour tests show timing with colors:\n\n| Color | Time | Meaning |\n|-------|------|---------|\n| \ud83d\udfe2 Green | <0.1s | Fast - Great! |\n| \ud83d\udfe1 Yellow | 0.1-0.5s | Medium - OK |\n| \ud83d\udd34 Red | 0.5-2s | Slow - Needs work |\n| \ud83d\udc80 Purple | >2s | Very slow - Problem! |\n\n#### Example Output\n\n```\n\ud83d\ude80 Starting Timed Test Run\n==================================================\nLegend: \ud83d\udfe2 <0.1s | \ud83d\udfe1 0.1-0.5s | \ud83d\udd34 >0.5s | \ud83d\udc80 >2s\n==================================================\n\n\ud83c\udfc3 Running: tests.monitor.test_django_base ... \ud83d\udfe2 0.045s \u2705\n\ud83c\udfc3 Running: tests.monitor.test_metrics ... \ud83d\udfe1 0.234s \u2705\n\ud83c\udfc3 Running: tests.integration.test_api ... \ud83d\udd34 0.678s \u2705\n\n\ud83d\udcca PERFORMANCE SUMMARY\nTotal time: 0.957s\nAverage per test: 0.319s\n```\n\n### Common Testing Tasks\n\n#### Run Specific Tests\n\n```bash\n# Test only monitor module\npython test_runner.py --module monitor\n\n# List all test modules\npython test_runner.py --list-modules\n```\n\n#### Build and Clean\n\n```bash\n# Clean everything\n./c_test_runner.sh clean\n\n# Rebuild C libraries\n./c_test_runner.sh build\n\n# Run benchmarks\n./c_test_runner.sh benchmark\n```\n\n#### Before You Commit\n\nAlways run these commands:\n\n```bash\n# 1. Check Python tests pass\npython test_runner.py\n\n# 2. Check C tests pass\n./c_test_runner.sh test\n\n# 3. Check code style\nblack django_mercury/\nruff check django_mercury/\n```\n\n### Adding Your Own Tests\n\n#### Python Tests\n\nCreate a file in `tests/` directory:\n\n```python\n# tests/test_my_feature.py\nimport unittest\nfrom django_mercury import DjangoMercuryAPITestCase\n\nclass TestMyFeature(DjangoMercuryAPITestCase):\n def test_feature_works(self):\n # Your test here\n response = self.client.get('/api/test/')\n self.assertEqual(response.status_code, 200)\n```\n\n#### C Tests\n\nCreate a file in `django_mercury/c_core/tests/`:\n\n```c\n// simple_test_myfeature.c\n#include <stdio.h>\n#include <assert.h>\n\nint main() {\n printf(\"Testing my feature...\\n\");\n // Your test here\n assert(1 == 1);\n printf(\"\u2705 Test passed!\\n\");\n return 0;\n}\n```\n\n### Getting Help\n\n- **Test failures?** Check the error message first\n- **Slow tests?** Look for `time.sleep()` or database queries\n- **C compilation errors?** Run `./c_test_runner.sh clean` then `build`\n- **Still stuck?** Open an issue with your test output\n\n## \ud83c\udfaf Real Results at EduLite\n\nBefore Mercury:\n- UserSearchView used **825 queries** to show one page\n- We could not see speed problems\n- Students with slow internet could not use the app\n\nAfter Mercury:\n- Found the exact problem\n- Fixed it to use only **12 queries**\n- Now we check speed on every code change\n\n## \ud83d\udea7 Future Plans\n\n### Phase 1: First Release \u2705\n- \u2705 Watch performance\n- \u2705 Find N+1 problems\n- \u2705 Show helpful guides\n- \u2705 Available on PyPI\n\n### Phase 2: Make It Better\n- \ud83d\udd1c Fix test problems\n- \ud83d\udd1c Support all view types\n- \ud83d\udd1c Track speed over time\n- \ud83d\udd1c Find when code gets slower\n- \ud83d\udd1c Better guides and examples\n\n### Phase 3: Add AI Help\n- \ud83d\udd1c AI suggests fixes\n- \ud83d\udd1c Create fixes you can review\n- \ud83d\udd1c Help new developers learn\n- \ud83d\udd1c Let you add custom checks\n\n## \ud83e\udd1d Contributing\n\nMercury is part of [EduLite](https://github.com/ibrahim-sisar/EduLite) and [Human in the Loop](https://github.com/80-20-Human-In-The-Loop). We welcome everyone.\n\n### Our Values\n\n- **Education First**: Tools should teach, not just find problems\n- **Human Understanding**: You control your code\n- **Open Source**: Built together, shared with everyone\n\n### How You Can Help\n\n1. **Test Mercury** - Try it on your Django project\n2. **Report Problems** - Tell us what doesn't work\n3. **Share Ideas** - Suggest improvements\n4. **Write Code** - Fix bugs or add features\n5. **Improve Docs** - Make them clearer\n6. **Help Others** - Answer questions\n\n### Getting Started\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n**New to open source?** Start here:\n- Look for \"good first issue\" labels\n- Ask questions - we're here to help\n- Small fixes matter too\n\n## \ud83c\udfeb Made for Learning\n\nMercury was made for [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn even with slow internet. Mercury helps by:\n\n- Working on slow computers\n- Teaching as it tests\n- Helping developers learn\n- Making apps work for everyone\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3.0).\n\n### Why GPL-3.0?\n\nWe use GPL-3.0 because it matches our values:\n\n- **\ud83c\udf0d Open**: Code stays open for everyone\n- **\ud83c\udd93 Free**: You can use, study, share, and improve it\n- **\u2696\ufe0f Fair**: Improvements must be shared\n- **\ud83e\udd1d Copyleft**: Stays free forever\n\nIf you share a changed version, you must:\n- Share your code\n- Use GPL-3.0 license\n- Keep all notices\n- List your changes\n\nThis keeps knowledge open for all.\n\nFor the full license text, see [LICENSE](LICENSE) or visit [GNU GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.html).\n\n## \ud83d\ude4f Thanks To\n\n- [EduLite Team](https://github.com/ibrahim-sisar/EduLite) - For showing us the need\n- [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) - For the ideas\n- Django/DRF Community - For the tools\n\n---\n\n**Mercury**: Making performance testing simple for everyone.\n\n*Built with \u2764\ufe0f by developers who believe people should understand their code.*\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A performance testing framework for Django that helps you understand and fix performance issues, not just detect them",
"version": "0.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/Django-Mercury/Performance-Testing/issues",
"Changelog": "https://github.com/Django-Mercury/Performance-Testing/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Django-Mercury/Performance-Testing#readme",
"Homepage": "https://github.com/Django-Mercury/Performance-Testing",
"Repository": "https://github.com/Django-Mercury/Performance-Testing.git"
},
"split_keywords": [
"django",
" performance",
" testing",
" monitoring",
" optimization",
" n+1",
" queries",
" profiling",
" mercury",
" rest-framework",
" api",
" benchmarking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9d0c287e60b924400bd0ccad5cdd62c26ac0e284f9c27b54e99e8d6c6db5917c",
"md5": "280df6fcdd79eb70c4a2fda72c87b543",
"sha256": "ab6083790140019d6de4d3e3c6723ca9c32487945204f6459b63e1440376bdea"
},
"downloads": -1,
"filename": "django_mercury_performance-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "280df6fcdd79eb70c4a2fda72c87b543",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 235765,
"upload_time": "2025-08-03T14:55:31",
"upload_time_iso_8601": "2025-08-03T14:55:31.191956Z",
"url": "https://files.pythonhosted.org/packages/9d/0c/287e60b924400bd0ccad5cdd62c26ac0e284f9c27b54e99e8d6c6db5917c/django_mercury_performance-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e6e1933212934ab0d3a20a7ea0ec303760a20d8e58230183b4fa9a9b0288bddb",
"md5": "b4ad68e7481a7cf7b24e95512d2d6c0d",
"sha256": "abf009017caab572c27a47330e562b9a1dff93897fa327c815632f34db2b7093"
},
"downloads": -1,
"filename": "django_mercury_performance-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b4ad68e7481a7cf7b24e95512d2d6c0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 253854,
"upload_time": "2025-08-03T14:55:32",
"upload_time_iso_8601": "2025-08-03T14:55:32.756223Z",
"url": "https://files.pythonhosted.org/packages/e6/e1/933212934ab0d3a20a7ea0ec303760a20d8e58230183b4fa9a9b0288bddb/django_mercury_performance-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 14:55:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Django-Mercury",
"github_project": "Performance-Testing",
"github_not_found": true,
"lcname": "django-mercury-performance"
}