179 lines
No EOL
4.9 KiB
Text
179 lines
No EOL
4.9 KiB
Text
---
|
|
.title = "Testing",
|
|
.date = @date("2025-10-20T00:00:00"),
|
|
.author = "Igor Támara",
|
|
.layout = "tutorial.shtml",
|
|
.draft = false,
|
|
.custom = {
|
|
.githubedit = "/docs/testing.md",
|
|
.codepath ="test",
|
|
},
|
|
---
|
|
Currently flow tests are aimed to work as unit tests, it always is a good
|
|
idea to review the
|
|
[zig tests documentation](https://ziglang.org/documentation/master/#Zig-Test)
|
|
and also an
|
|
[introduction to testing](https://pedropark99.github.io/zig-book/Chapters/03-unittests.html).
|
|
|
|
To work with tests you will need to:
|
|
|
|
* [Clone](https://github.com/neurocyte/flow) the repo
|
|
* Have [zig installed](https://ziglang.org/download/). Highly recommended to use
|
|
[anyzig](https://github.com/marler8997/anyzig)
|
|
|
|
Flow tests are placed in the directory `test`.
|
|
|
|
## Running the tests
|
|
|
|
To run the full set of tests, inside flow, use `F5`, which runs a task that
|
|
invokes:
|
|
|
|
```
|
|
zig build test
|
|
```
|
|
|
|
it will work if flow was invoked from the project root, which is the same
|
|
place that you would normally run the tests when on the terminal.
|
|
|
|
### Run a particular test
|
|
|
|
To run an specific test use `Dtest-filter` option with the name of your
|
|
test, i.e., for the test called **test_block_name** use:
|
|
|
|
```
|
|
zig build test -Dtest-filter="test_block_name"
|
|
```
|
|
|
|
## Adding tests
|
|
|
|
Tests are needed when:
|
|
|
|
* There is some logic that might be difficult to understand given it's
|
|
nature, for example, when there are a lot of branching
|
|
* You find something that could be changed in the future affecting the
|
|
current behavior
|
|
* A bug is fixed
|
|
* A defined behavior could be thought different, for example when in a mode,
|
|
it was defined that something might diverge from other programs.
|
|
|
|
Tests are placed under `test` directory. Add your test in the file that
|
|
exercises the functionality and makes proof of it behaving as expected.
|
|
Maintain the logic test as simple as possible. It's possible to add
|
|
additional functions to make the tests readable and extendable though.
|
|
|
|
public functions are stratightforward tested, while there are some
|
|
conventions for testing private functions.
|
|
|
|
### Testing private functions
|
|
|
|
Some internal logic of a module can be tested without the need to be
|
|
exposed to other modules.
|
|
|
|
In such cases the module that has the logic should provide a pub
|
|
`test_internal`, by convention, exposing the target functionalities to
|
|
be tested.
|
|
|
|
For example in `src/tui/mode/helix.zig`, `test_internal` exposes the private
|
|
function
|
|
|
|
```zig
|
|
fn move_cursor_long_word_right_end(root: Buffer.Root, cursor: *Cursor, metrics: Buffer.Metrics) error{Stop}!void
|
|
```
|
|
|
|
with
|
|
|
|
```zig
|
|
pub const test_internal = struct {
|
|
pub const move_cursor_long_word_right = private.move_cursor_long_word_right;
|
|
.
|
|
.
|
|
.
|
|
};
|
|
```
|
|
|
|
And in `test/tests_helix.zig`, helix is imported as
|
|
|
|
```zig
|
|
const helix = @import("tui").exports.mode.helix;
|
|
```
|
|
|
|
Later on using the function `move_cursor_long_word_right` as
|
|
|
|
```zig
|
|
try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metrics);
|
|
```
|
|
|
|
In case there is need of a new test file for concern separation, continue
|
|
to the next section.
|
|
|
|
## Adding a new test file
|
|
|
|
Three steps are required for adding a new test file:
|
|
|
|
1. Create a new test file
|
|
1. Include the test to the set of tests
|
|
1. Optionally, make available a module to the build system
|
|
for your particular test
|
|
|
|
### Create the test file
|
|
|
|
Place your test file under `test` directory, the name should be prefixed
|
|
with `tests_`.
|
|
|
|
For the rest of this section we will use as a sample
|
|
`tests_project_manager.zig`.
|
|
|
|
### Include the test file
|
|
|
|
Tests files are linked via `test/tests.zig`, import your new test_file
|
|
alphabetically as in our sample:
|
|
|
|
```zig
|
|
pub const project_manager = @import("tests_project_manager.zig");
|
|
```
|
|
|
|
### Import required modules when building tests
|
|
|
|
In `build.zig` import the required module under `tests.root_module`, for
|
|
the current example:
|
|
|
|
```zig
|
|
tests.root_module.addImport("project_manager", project_manager_mod);
|
|
```
|
|
|
|
[Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c)
|
|
of adding a new test file for project manager.
|
|
|
|
## FAQ on tests
|
|
|
|
### I need to test something that requires importing the editor ¿What do I do?
|
|
|
|
There are two paths from here:
|
|
|
|
1. Refactor your code to test the lower level functions
|
|
1. Extend the tests to automate via external tools
|
|
|
|
|
|
### Refactor to test lower level functions
|
|
|
|
Refactor the functions involved in the functionality to make them
|
|
not rely directly with editor and other higher level componets, and
|
|
test the lower level ones.
|
|
|
|
An example of this can be seen in commands
|
|
|
|
### Use aditional tools to test a running flow session
|
|
|
|
Use additional tools to invoke the built editor and send keys to
|
|
it, modify a file and then compare the initial contents of the file
|
|
and the resulting contents of your file and the expected ones.
|
|
|
|
If in doubt about how to do something,
|
|
[please ask](https://discord.com/invite/4wvteUPphx).
|
|
|
|
|
|
## Next steps
|
|
|
|
* [How to contribute](/docs/contributing)
|
|
* [User Documentation](/docs)
|
|
* [Other Flow topics](/docs/architecture) |