Skip to content

Commit 04ff426

Browse files
committed
README: Expand "Writing Unittests" section
This commit clarifies how test cases are expected to import or address modules of a Sublime Text package as it slightly changed in PR #277.
1 parent aa3ed3d commit 04ff426

File tree

1 file changed

+48
-2
lines changed

1 file changed

+48
-2
lines changed

README.md

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -338,17 +338,63 @@ see also: https://docs.python.org/3/library/warnings.html#warning-filter
338338
UnitTesting is based on python's `unittest` library.
339339
Any valid unittest test case is allowed.
340340

341+
Module lookup and imports respect Sublime Text's package ecosystem.
342+
Global imports lookup modules in:
343+
344+
- `${data}/sublime-text/Lib/python38/`
345+
- `${data}/sublime-text/Packages/`
346+
- `${install}/Packages/`
347+
348+
A common ST package's folder structure may look like this:
349+
350+
```
351+
Packages
352+
├── ...
353+
└── Package To Test
354+
├── sub_package
355+
| ├── __init__.py
356+
| └── module.py
357+
├── tests
358+
| ├── __init__.py
359+
| └── test_module.py
360+
└── plugin.py
361+
```
362+
363+
The `Package To Test` is the root package being tested,
364+
which contains `tests/` as a sub-package, next to vendored python packages
365+
or primary business logic to test in `sub_package`.
366+
367+
This differs from how normal python package repositories organize tests next to package's source folder.
368+
369+
It requires package name (`Package To Test`) to be included in all absolute module names.
370+
371+
> [!NOTE]
372+
>
373+
> ST packages don't need and should not contain a top-level `__init__.py` module to be treated like a normal python package.
374+
375+
Test modules can use relative imports to access all modules.
376+
341377
Example:
342378

343-
_tests/test_myunit.py_
379+
_Package To Test/tests/test_module.py_
344380

345381
```py
382+
from unittest.mock import patch
346383
from unittesting import TestCase
347384
385+
from ..sub_package.module import ClassToTest
386+
387+
348388
class MyTestCase(TestCase):
349389
350390
def test_something(self):
351-
self.assertTrue(True)
391+
obj = ClassToTest()
392+
self.assertTrue(obj.some_method() == True)
393+
394+
def test_with_mock(self)
395+
# need absolute module name including ST package here
396+
with patch("Package To Test.sub_package.module") as mock:
397+
...
352398
```
353399

354400

0 commit comments

Comments
 (0)