Debian Codegraph @

.github/prompts/mssql-django-run-unit-tests.prompt.md

raw
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 ```