|
1 | 1 |
|
2 | | - # Dockerized-NorLab-Project guideline |
3 | | - |
4 | | -Stand-alone version with a PATH-accessible bash script approach |
5 | | - |
| 2 | +# Repository Guidelines |
| 3 | + |
6 | 4 | ## General Requirements: |
7 | 5 | - Don't repeat yourself. Use already implemented code such as: |
8 | 6 | - `load_repo_main_dotenv.bash` |
9 | | - - `import_dnp_lib.bash` |
| 7 | + - `import_dna_lib.bash` |
10 | 8 | - `load_super_project_config.bash` |
11 | | - - N2ST library |
12 | | - - NBS library |
| 9 | + - _N2ST_ library |
| 10 | + - _NBS_ library |
13 | 11 | - Path management: |
14 | 12 | - Case 1 › system wide: |
15 | | - - via symlink `/usr/local/bin/dnp` → `/path/to/dockerized-norlab-project/src/bin/dnp`; |
16 | | - - via `~/.bashrc` ← `PATH=${PATH}:${DNP_PATH}:${NBS_PATH}:${N2ST_PATH}`. |
| 13 | + - via symlink `/usr/local/bin/dna` → `/path/to/dockerized-norlab-project/src/bin/dna`; |
| 14 | + - via `~/.bashrc` ← `PATH=${PATH}:${DNA_PATH}:${NBS_PATH}:${N2ST_PATH}`. |
17 | 15 | - Case 2 › manual load: |
18 | | - - each super project can optionally use the env var `DNP_PATH`, `NBS_PATH` and `N2ST_PATH` define in `.env.dockerized-norlab-project`. |
| 16 | + - each super project can optionally use the env var `DNA_PATH`, `NBS_PATH` and `N2ST_PATH` define in `.env.dockerized-norlab-project`. |
19 | 17 |
|
20 | | -## Repository Development Organization |
21 | | -- `src/bin/dnp` is the DNP application entrypoint |
22 | | -- `src/lib/` contain lybrary files |
| 18 | +## Repository Organization |
| 19 | +- `src/bin/dna` is the DNA application entrypoint |
| 20 | +- `src/lib/` contain library files |
23 | 21 | - `tests/` contain tests files |
24 | 22 | - `tests/tests_bats/` contain N2ST bats framework files that are mainly used for unit-testing |
25 | | -- `tests/tests_dryrun_and_tests_scripts/` contain integration test (see details bellow) |
26 | | -- `utilities` contain external libraries such as N2ST and NBS |
| 23 | +- `tests/tests_dryrun_and_tests_scripts/` contain integration test (see details below) |
| 24 | +- `utilities/` contain external libraries such as N2ST and NBS |
27 | 25 | - `utilities/tmp/dockerized-norlab-project-mock` is use for cloning a fresh copy of a mock "super project" from https://github.com/norlab-ulaval/dockerized-norlab-project-mock.git on test execution. |
28 | | - `dockerized-norlab-project-mock` is a mock of how a user would install and uses DNP. We refer to this as a "super project" or the "user side". |
| 26 | + `dockerized-norlab-project-mock` is a mock of how a user would install and uses DNA. We refer to this as a "super project" or the "user side". |
| 27 | + |
| 28 | +## Version Control |
| 29 | +- Never `git add` or `git commit` changes, all changes require explicit code review and acceptance by the codeowner. |
29 | 30 |
|
30 | | -## Tests Requirements: |
| 31 | +## Tests Requirements |
| 32 | +- In the context of testing: |
| 33 | + - the definition of _pass_ is that a test exit whitout error. Synomym: _green_, _successfull_; |
| 34 | + - the definition fo _done_ mean that all tests where executed and all tests passed. |
31 | 35 |
|
32 | 36 | ### Testing Strategy |
33 | 37 | - Inspect the tested script/functions for business logic related error or implementation error. Propose correction before going forward if any. |
34 | 38 | - Write tests who chalenge the intended functionality or behavior. |
35 | 39 | - Write **Unit-tests** and/or **Integration tests**: |
36 | 40 | - All new scripts or functionalities need to have (either or both): |
37 | 41 | - **Unit-tests**: |
38 | | - - use [N2ST](https://github.com/norlab-ulaval/norlab-shell-script-tools) bats tests tools for unit-test (See `tests/run_bats_core_test_in_n2st.bash` script) and a corresponding bats unit-test `.bats` file in the `tests/tests_bats/` directory. Bats tests will be running in a docker container in complete isolation with a copy of the source code. |
| 42 | + - Those are tests that check if the core expected behaviors are satisfy. It test a piece of code in a stand alone fashion. |
| 43 | + - Use [N2ST](https://github.com/norlab-ulaval/norlab-shell-script-tools) bats tests tools for unit-test (See `tests/run_bats_core_test_in_n2st.bash` script) and a corresponding bats unit-test `.bats` file in the `tests/tests_bats/` directory. N2ST Bats tests are running in a docker container in complete isolation with a copy of the source code. |
39 | 44 | - **Integration tests**: |
40 | | - - those are test case where there is multiple script interacting whith each other or we want to assess execution from begining to end; |
41 | | - - those tests are devided in two categories: |
| 45 | + - Those are test case where there is multiple script interacting whith each other or we want to assess execution from begining to end; |
| 46 | + - Those tests are devided in two categories: |
42 | 47 | - Dryrun: either make use of a `--dry-run` flag implemented in the script or make use of the docker `--dry-run` flag; |
43 | 48 | - Test: all other integration test case that are not dryrun. |
44 | | - - Use [NBS](https://github.com/norlab-ulaval/norlab-build-system) tests tools for integration-test (See `tests/run_all_dryrun_and_tests_script.bash` script) and a corresponding `test_*` or `dryrun_*` script in the `tests/tests_dryrun_and_tests_scripts/` directory. |
45 | | -- One test file (`.bats` or `.bash`) per coresponding source code script. |
| 49 | + - Use [NBS](https://github.com/norlab-ulaval/norlab-build-system) tests tools for integration-test (See `tests/run_all_dryrun_and_tests_script.bash` script) and a corresponding `test_*` or `dryrun_*` script in the `tests/tests_dryrun_and_tests_scripts/` directory. |
| 50 | + - New integration test script must go in the `tests/tests_dryrun_and_tests_scripts/` directory. |
| 51 | +- Their should be at least one test file (`.bats` and/or `.bash`) per coresponding source code script. |
46 | 52 | - Identify relevant test cases e.g., behavior validation, error handling, desired user feedback, ... |
47 | | -- If the tested script implement helper functions (i.e., support function meant to be used by the main function), test those functions first. |
48 | 53 | - Divide test file by test cases: one test function per test case. |
| 54 | +- If the tested script implement helper functions (i.e., support function meant to be used by the main function), test those functions first. |
49 | 55 | - Provide a summary explanation of the test case: |
50 | 56 | - What does it test for; |
51 | 57 | - What's the test expected outcome (i.e, should it pass or fail); |
52 | 58 | - If you do mock something, justify why. |
53 | 59 | - All tests in the `tests/` directory must pass. |
54 | | -- The definition fo _Done_ mean that tests where executed and all tests passed. |
| 60 | +- Always execute all unit-tests and all integration tests before submiting. |
| 61 | + |
55 | 62 |
|
56 | 63 | ### Instruction On Mocking |
57 | 64 | - You can mock shell core command an docker command. |
58 | 65 | - You can mock `docker [OPTIONS|COMMAND]` commands and `git [OPTIONS|COMMAND]` commands. |
59 | 66 | - Don't mock the functions that are tested in the tested script. |
60 | | -- Avoid mocking n2st functions, at the expection of those in `src/function_library/prompt_utilities.bash`. For eaxample, instead of re-implementaing `n2st::seek_and_modify_string_in_file`, just load the real one and test that the content of the file at `file_path` has been updated? You can find the real one in `src/function_library/general_utilities.bash`. |
| 67 | +- Avoid mocking N2ST functions, at the exception of those in `${N2ST_PATH}/src/function_library/prompt_utilities.bash`. For example, instead of re-implementing `n2st::seek_and_modify_string_in_file`, just load the real one and test that the content of the file at `file_path` has been updated? You can find the real one in `${N2ST_PATH}/src/function_library/general_utilities.bash`. |
61 | 68 | - Avoid mocking the `read` command. Instead use `echo 'y'` or `echo 'N'` for piping a keyboard input to the function who use the `read` command which in turn expect a single character, example: `run bash -c "echo 'y' | <the-tested-function>"`. Alternatively, use the `yes [n]` shell command which optionaly send [y|Y|yes] n time, example: `run bash -c "yes 2 | <the-tested-function>"`. |
62 | 69 |
|
63 | 70 | ### Instruction On Bats Tests |
64 | 71 | - Use bats framework `bats-file` helper library provide tools for temporary directory management, such as the `temp_make` and `temp_del` functions. |
65 | 72 | Reference https://github.com/bats-core/bats-file?tab=readme-ov-file#working-with-temporary-directories |
66 | 73 | - Use bats test function `assert_file_executable` and `assert_file_not_executable` to test executable. |
67 | 74 | - Use bats test function `assert_symlink_to` and `assert_not_symlink_to` to test symlink. |
68 | | -- You can test symlink `/usr/local/bin/dnp` directly without mocking since bats tests are running in a docker container in complete isolation. |
| 75 | +- You can test directory/file mode, existence, permision, content and symlink directly without mocking since bats tests are running in a docker container in complete isolation. |
| 76 | +- Test `/usr/local/bin/dna` symlink related logic directly without mocking. |
69 | 77 |
|
70 | 78 | Bats helper library documentation: |
71 | 79 | - https://github.com/bats-core/bats-assert |
72 | 80 | - https://github.com/bats-core/bats-file |
73 | 81 | - https://github.com/bats-core/bats-support |
74 | 82 |
|
75 | | -### Bats Tests Execution |
| 83 | +### Instruction On Tests Execution |
76 | 84 | - Don't directly execute `.bats` files, instead execute from the repository root `bash ./tests/run_bats_core_test_in_n2st.bash tests/tests_bats/<bats-file-name>.bats`. |
77 | 85 | - Don't set tests script in executable mode instead execute them with `bash <the-script-name>.bash`. |
| 86 | +- Always run unit-tests before integration tests. |
| 87 | +- Never run integration tests if any unit-tests fail. |
0 commit comments