| 1 |
# Running mssql-django Unit Tests |
| 2 |
|
| 3 |
This guide covers running the mssql-django package's own unit tests (42 tests across 11 test files). |
| 4 |
|
| 5 |
## Prerequisites |
| 6 |
|
| 7 |
### 1. SQL Server Database |
| 8 |
|
| 9 |
You need a running SQL Server instance. Options: |
| 10 |
|
| 11 |
#### Option A: Docker (Recommended for local development) |
| 12 |
|
| 13 |
```bash |
| 14 |
# Start SQL Server 2022 in Docker |
| 15 |
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=MyPassword42" \ |
| 16 |
-p 1433:1433 --name sqlserver -d mcr.microsoft.com/mssql/server:2022-latest |
| 17 |
|
| 18 |
# Wait for SQL Server to start (about 20 seconds) |
| 19 |
sleep 20 |
| 20 |
|
| 21 |
# Verify it's running |
| 22 |
docker logs sqlserver 2>&1 | tail -5 |
| 23 |
``` |
| 24 |
|
| 25 |
#### Option B: Use existing SQL Server |
| 26 |
|
| 27 |
Update `testapp/settings.py` with your connection details. |
| 28 |
|
| 29 |
### 2. ODBC Driver |
| 30 |
|
| 31 |
Install Microsoft ODBC Driver for SQL Server: |
| 32 |
|
| 33 |
```bash |
| 34 |
# Ubuntu 24.04 |
| 35 |
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg |
| 36 |
echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/24.04/prod noble main" | sudo tee /etc/apt/sources.list.d/mssql-release.list |
| 37 |
sudo apt-get update |
| 38 |
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev |
| 39 |
``` |
| 40 |
|
| 41 |
**Note:** Ubuntu 24.04 only has ODBC Driver 18 available. The default `testapp/settings.py` uses Driver 17. You may need to update: |
| 42 |
|
| 43 |
```python |
| 44 |
# In testapp/settings.py, change: |
| 45 |
"OPTIONS": {"driver": "ODBC Driver 17 for SQL Server", ...} |
| 46 |
# To: |
| 47 |
"OPTIONS": {"driver": "ODBC Driver 18 for SQL Server", "extra_params": "TrustServerCertificate=yes", ...} |
| 48 |
``` |
| 49 |
|
| 50 |
### 3. Python Dependencies |
| 51 |
|
| 52 |
```bash |
| 53 |
# Install mssql-django in development mode with test dependencies |
| 54 |
pip install -e ".[test]" |
| 55 |
``` |
| 56 |
|
| 57 |
The `[test]` extra installs `unittest-xml-reporting` which provides the `xmlrunner` module required by the test runner. |
| 58 |
|
| 59 |
**Warning:** Do NOT install the old `xmlrunner` package directly - it's incompatible with Python 3.12+. |
| 60 |
|
| 61 |
## Running Tests |
| 62 |
|
| 63 |
### Run all mssql-django tests |
| 64 |
|
| 65 |
```bash |
| 66 |
python manage.py test --noinput |
| 67 |
``` |
| 68 |
|
| 69 |
Expected output: `Ran 42 tests in ~22s - OK` |
| 70 |
|
| 71 |
### Run specific test module |
| 72 |
|
| 73 |
```bash |
| 74 |
python manage.py test testapp.tests.test_base -v 2 |
| 75 |
``` |
| 76 |
|
| 77 |
### Run specific test class |
| 78 |
|
| 79 |
```bash |
| 80 |
python manage.py test testapp.tests.test_base.TestEncodeValue -v 2 |
| 81 |
``` |
| 82 |
|
| 83 |
### Run specific test method |
| 84 |
|
| 85 |
```bash |
| 86 |
python manage.py test testapp.tests.test_base.TestEncodeValue.test_simple_value -v 2 |
| 87 |
``` |
| 88 |
|
| 89 |
## Test Structure |
| 90 |
|
| 91 |
- Tests are in `testapp/tests/` |
| 92 |
- Test runner: `testapp/runners.py` (ExcludedTestSuiteRunner) |
| 93 |
- Settings: `testapp/settings.py` |
| 94 |
|
| 95 |
## Cleanup |
| 96 |
|
| 97 |
```bash |
| 98 |
# Stop and remove SQL Server container |
| 99 |
docker stop sqlserver && docker rm sqlserver |
| 100 |
|
| 101 |
# Restore settings.py if modified |
| 102 |
git checkout testapp/settings.py |
| 103 |
``` |
| 104 |
|
| 105 |
## Troubleshooting |
| 106 |
|
| 107 |
### "Can't open lib 'ODBC Driver 17 for SQL Server'" |
| 108 |
|
| 109 |
Install ODBC Driver 18 and update settings.py (see Prerequisites section). |
| 110 |
|
| 111 |
### "Login failed for user 'sa'" |
| 112 |
|
| 113 |
Wait longer for SQL Server to start, or check the password matches settings.py. |
| 114 |
|
| 115 |
### ModuleNotFoundError: No module named 'xmlrunner' |
| 116 |
|
| 117 |
```bash |
| 118 |
pip install unittest-xml-reporting |
| 119 |
# Or: pip install -e ".[test]" |
| 120 |
``` |