diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index b0e2658..4275760 100644 --- a/content/docs/architecture.smd +++ b/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). \ No newline at end of file diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index 5ee9de7..4a10e40 100644 --- a/content/docs/contributing.smd +++ b/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. - diff --git a/content/docs/testing.smd b/content/docs/testing.smd new file mode 100644 index 0000000..b621101 --- /dev/null +++ b/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).