|
| 1 | +# Development Guide |
| 2 | + |
| 3 | +## Code style |
| 4 | + |
| 5 | +We follow [Google Style Python Docstring](https://google.github.io/styleguide/pyguide.html) for development. |
| 6 | + |
| 7 | +Following is an typical example: |
| 8 | + |
| 9 | +```python |
| 10 | +class SampleClass: |
| 11 | + """Summary of class here. |
| 12 | +
|
| 13 | + Longer class information... |
| 14 | + Longer class information... |
| 15 | +
|
| 16 | + """ |
| 17 | + |
| 18 | + def __init__(self, likes_spam: bool = False): |
| 19 | + """Initializes the instance based on spam preference. |
| 20 | +
|
| 21 | + Args: |
| 22 | + likes_spam: Defines if instance exhibits this preference. |
| 23 | + """ |
| 24 | + self.likes_spam = likes_spam |
| 25 | + self.eggs = 0 |
| 26 | + |
| 27 | + def public_method(self, a, b): |
| 28 | + """Performs operation blah. |
| 29 | +
|
| 30 | + Long description here. |
| 31 | +
|
| 32 | + Args: |
| 33 | + a (int): xxx |
| 34 | + b (int/str): xxx |
| 35 | +
|
| 36 | + Returns: |
| 37 | + t (bool): xxx |
| 38 | + k (int): xxx |
| 39 | + """ |
| 40 | + # function implementation goes here |
| 41 | +``` |
| 42 | + |
| 43 | +## Run unit tests |
| 44 | + |
| 45 | +We use `tox` to run unit tests. You should install `tox` in your development environemnt |
| 46 | +``` |
| 47 | +pip install tox |
| 48 | +``` |
| 49 | +Currently we only use python3.10 to run tests. If you don't have python3.10 in your system, you can use conda. After conda is installed, you should install tox conda plugin by running |
| 50 | +``` |
| 51 | +pip install tox-conda |
| 52 | +``` |
| 53 | +After tox is ready, you can run all the unit test by running |
| 54 | +``` |
| 55 | +tox |
| 56 | +``` |
| 57 | +Please note tox will reuse the same virtual environment which is initialized by installing all packages listed in `requirements.txt` and `requirements-dev.txt`. If any of above files are modified, you should re-create virtual environment by running |
| 58 | +``` |
| 59 | +tox -r |
| 60 | +``` |
| 61 | + |
| 62 | +To run a single unit test task during development, you can run |
| 63 | + |
| 64 | +``` |
| 65 | +pytest tests/your_test_file.py |
| 66 | +``` |
| 67 | + |
| 68 | +### Unit tests in AzureDevops pipeline |
| 69 | + |
| 70 | +We use AzureDevops to run unit tests before you can merge your PR to main branch. You can find the pipeline definition in `azure-pipelines.yml`. |
| 71 | + |
| 72 | +Please note that in AzureDevops pipeline agent, no gpu is available. So you must make sure your unit tests can run on cpu to pass the CI. Two options are available: |
| 73 | +1. Use `@replace_all_device_with('cpu')` decorator to replace all devices with cpu. Please refer to other tests for example. |
| 74 | +2. Mark your test case only work on gpu by using `@pytest.mark.skipif(not torch.cuda.is_available(), reason='lack of gpu devices')` decorator. Please refer to existing tests for example. |
| 75 | + |
| 76 | +Before you push your code, please run tests at least on GPU machines to make sure all tests can pass. GPU test cases can't be run in AzureDevops pipeline. Of course, it would be better if you can run all tests on both GPU and CPU machines. |
| 77 | + |
| 78 | +### Run unit tests in vscode |
| 79 | + |
| 80 | +VS Code has a great support to unit tests. You can run/debug every tests easily in VS Code. Please refer to this document to set up your environment https://code.visualstudio.com/docs/python/testing |
| 81 | + |
| 82 | +Another trick is, if you want to step into pakcage source code, you can add the following config to your .vscode/launch.json: |
| 83 | +``` |
| 84 | +{ |
| 85 | + "name": "Debug Unit Test", |
| 86 | + "type": "python", |
| 87 | + "request": "test", |
| 88 | + "justMyCode": false, |
| 89 | +}, |
| 90 | +``` |
| 91 | + |
| 92 | +### Write Unit Tests |
| 93 | +1. If you need to use torchrun, please refer to `unit_test/launch_torchrun.py`, and you can find examples in `unit_tests/runtime/test_runtime_collectives.py`. Please note that `torchrun` is very slow, you should reduce its usage as possible. |
| 94 | +2. If you want to mock up any functions/methods, please use pytest-mock. |
| 95 | +3. **NOTE**: The name of test files and test functions must start with `test_` |
0 commit comments