Add testing section

content/docs/architecture.smd

@@ -4,9 +4,17 @@
 .author = "Igor Támara",
 .layout = "tutorial.shtml",
 .draft = false,
-.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture.smd"},
+.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture.smd",
+  .prevurl = "https://github.com/neurocyte/flow",
+  .prevtext = "Code",
+  .nexturl = "/docs/contributing",
+  .nexttext = "Contributing",
+  .topurl = "/docs/",
+  .toptext = "Docs",
+}
 ---
-
+Head to: [Contribution guidelines](/docs/contributing).
+ b
 This document describes in a general way, concepts that help to
 understand how the code is organized and where to look at when starting
 to contribute developing Flow Control.  Make sure you have read
@@ -72,9 +80,13 @@ while in Windows there is an special GUI.
 processes synchronization and allows sending messages between
 different flow components, for example, when a widget needs
 updating information from changing states of internal data and
-when components or external processes take time. For example,
-tree-sitter queries to highlight the current file of a particular
-language, LSPs, git, running a `shell` command via a `task`.
+when components or external processes take time and need to return
+an answer, all this without blocking the user interface. Tree-sitter
+queries to highlight the current file of a particular
+language and LSPs usually take time by the nature of operations they
+perform, integration with git and running a `shell` command via a
+`task` all are coordinated thanks to the infrastructure that
+Thespian provides.
 
 ## Programming languages support
 
@@ -88,9 +100,6 @@ Currently one Language Server is supported for each language.
 The clipboard is used for copy, paste operations and there is also
 support to use the system clipboard, copying and pasting to/from it.
 
-Logging support offers various levels to give feedback for various
+Logging support offers various levels to give feedback for several
 actions that ease developing Flow itself and also are used to offer
 feedback via `logview`.
-
-
-We have some [contribution guidelines](/docs/contributing).

content/docs/contributing.smd

@@ -4,7 +4,14 @@
 .author = "Igor Támara",
 .layout = "tutorial.shtml",
 .draft = false,
-.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"},
+.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd",
+  .nexturl = "/docs/testing",
+  .nexttext = "Testing",
+  .topurl = "/docs/",
+  .toptext = "Docs",
+  .prevurl = "/docs/architecture",
+  .prevtext = "Architecture",
+}
 ---
 
 ## Asking for a feature
@@ -93,11 +100,12 @@ for future readers and commiters.
 
 It's possible that the test set grows as the project evolves, given
 that the amount of relationships among components increase the
-opportunity to generate regressions.
+opportunity to generate regressions. If you are new to zig a good
+place to start to learn about the codebase is
+[adding some tests](/docs/testing)
 
 ## Getting in touch.
 
 [Discord](https://discord.com/invite/4wvteUPphx) and
 [Github issues](https://github.com/neurocyte/flow/issues) are the
 main channels to do so.
-

content/docs/testing.smd

@@ -0,0 +1,76 @@
+---
+.title = "Testing",
+.date = @date("2025-10-20T00:00:00"),
+.author = "Igor Támara",
+.layout = "tutorial.shtml",
+.draft = false,
+.custom = {
+  .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/testing.md",
+  .prevurl = "/docs/contributing",
+  .prevtext = "Contributing",
+  .topurl = "/docs/architecture",
+  .toptext = "Architecture",
+  .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)
+
+## Running the tests
+
+To run the full set of tests, inside flow, use F6, which invokes
+
+```
+zig build test
+```
+
+it will work if flow was invoked from the root flow when you cloned the repo.
+
+## Run a particular test
+
+To run a particular test use
+
+```
+zig build test -Dtest-filter="test_block_name"
+```
+
+## Adding a new test file
+
+Tests files are linked via `tests.zig` and if your file test requires
+to import an additional module from flow, it can be done via the
+corresponding test step in `build.zig`, look for `test_step.dependOn`
+to find out where to make the module available for your test case
+need.
+
+## I need to test something that requires importing the editor
+
+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.
+
+### 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).