Lang ref: Explain Zig Test and Containers #9737
Conversation
|
For the Zig Test section, I focus more on the language aspects of testing. However, since there aren't separate pages for more comprehensive documentation for each tool in Zig's toolchain, I can add more information and examples for the test specific command line arguments. |
paulespinosa
force-pushed
the
langref-explain-zig-test-containers
branch
6 times, most recently
from
03fda3e
to
1aa7942
Compare
paulespinosa
force-pushed
the
langref-explain-zig-test-containers
branch
5 times, most recently
from
affdd3b
to
29ef85a
Compare
paulespinosa
force-pushed
the
langref-explain-zig-test-containers
branch
2 times, most recently
from
e994180
to
fb36d91
Compare
There was a problem hiding this comment.
This is too long to review and has quite some redundant information that should better be links to the other sections.
Below are some essentials after taking quite abit time to read.
Given that tests use containers and containers are often used (without definition) in section "Variables", I would propose moving "Zig Test" after "Values". "Containers" should probably go before "Zig Test" leading to the following structure:
- Introduction
- Zig Standard Library
- Hello World
- Comments
- Values
- Containers
- Zig Test
- Variables
Also testing memory leaks belongs into the allocator section
Personally I think explaining each builtin is not feasible and "Detecting Test Build" takes alot space with explaining only a 1-line information.
Test Tool Documentation also has a typo for the command, which should be written as zig test --help.
doc/langref.html.in
Outdated
| to make sure behavior meets expectations. {#syntax#}@import("builtin").is_test{#endsyntax#} | ||
| is available for code to detect whether the current build is a test build. | ||
| In addition to writing Zig code to create programs or libraries, Zig code can also be written to verify that the | ||
| code used for making programs or libraries are functioning correctly. Test code is written within one or more |
There was a problem hiding this comment.
-
Tests are not for verification, since that requires a proof over all possible inputs.
-
Tests describe expected results over a limited input set to minimize causal logical effects of faults. This mostly includes preventing and detecting regressions by testing the edge cases, but can also include other test strategies with respective goals.
-
Tests are also a tool to communicate intended usage patterns.
Probably keeping it as general and short as possible would be best here like in the original.
doc/langref.html.in
Outdated
| In addition to writing Zig code to create programs or libraries, Zig code can also be written to verify that the | ||
| code used for making programs or libraries are functioning correctly. Test code is written within one or more | ||
| {#syntax#}test{#endsyntax#} declarations as demonstrated in the <code class="file">introducing_zig_test.zig</code> | ||
| code sample below. |
There was a problem hiding this comment.
"code sample below" is redundant information.
see the wasi section just giving a colon to indicate reading below:
doc/langref.html.in
Outdated
| <p> | ||
| In the code sample below, the <code class="file">introducing_zig_test.zig</code> is shown again with comments | ||
| to explain parts of the code. The lines starting with {#syntax#}//{#endsyntax#} and {#syntax#}///{#endsyntax#} are | ||
| {#link|Comments#} that are useful for sharing information with other people. |
There was a problem hiding this comment.
Comments are explained in the comments section. Please link them instead of providing redundant information that the reader does not expect here.
doc/langref.html.in
Outdated
| </p> | ||
| {#code_begin|test|introducing_zig_test#} | ||
| // Using @import("std") causes the Standard Library to be represented as a structure (struct). | ||
| // The constant identifier `std` provides access to the structure's data and methods. |
There was a problem hiding this comment.
@importstd is explained in the hello world example.- Please link to the container section instead of explaining it here.
Probably containers belong in front of tests, so you can reuse the description and explain positioning of things, but that can be done in a second commit.
| // `try` is used to return an error to the test runner to notify it that the test failed. | ||
| // Errors and `try` are explained in another section of this documentation. | ||
| // The code below demonstrates a common way to verify something is true. | ||
|
|
There was a problem hiding this comment.
no empty space between documentation and the code it refers to.
This is too much text as comment that could be better link to the according sections.
doc/langref.html.in
Outdated
| } | ||
| {#code_end#} | ||
| <p> | ||
| <kbd>zig test</kbd> is a tool that runs test code. It packages the given Zig source file into the default test runner, |
There was a problem hiding this comment.
This section does not explain how tests are packages. I suspect it is one binary per file that contains all test cases.
doc/langref.html.in
Outdated
| <p> | ||
| <kbd>zig test</kbd> is a tool that runs test code. It packages the given Zig source file into the default test runner, | ||
| builds a test runner executable program, and then runs the test runner's executable program. The default test | ||
| runner is part of the {#link|Zig Standard Library#}. When the test runner is being built, it is provided with |
There was a problem hiding this comment.
"The default test runner is part of the {#link|Zig Standard Library#}." 2 sentences before you explained that zig test only uses the default test runner. I think there is missing something here.
doc/langref.html.in
Outdated
| Zig source file is not built using the <kbd>zig test</kbd> tool, the tests are omitted from the program/library. | ||
| </p> | ||
| <p> | ||
| <kbd>zig test</kbd> will only pass the given source file's top-level test declarations to the test runner. |
There was a problem hiding this comment.
Some lines above you mentioned only top-level decls are supported by the test system. This makes me wonder, if the "test runner" is different than the "default test runner".
|
Thank you @matu3ba! I had similar ideas about section re-organization. But, let's try your idea! I'll move this back to a draft pull request, work on the changes, then ping you when the changes are made. |
|
I forgot to mention that some of the repetition is meant to help maintain focus and support learning. Linking too much might detract new learners focus from the section being read and ultimately lose the reader. So, I try (will try) to highlight the main point of the linked section. This also is done to support the reader's understanding of the linked section if it was already read. However, the repetition was noticed which means the balance was off. Again, thank you! |
Its probably easier to create a new branch for this stuff, so that the review history is not cluttered. |
The langref main goal is to work as quick reference for each section. The "hello world" is the exception, if you compare it to the rest of the reference. From my perspective to learn (practically) ziglings and ziglearn should be used as linked in the language website. |
This commit explains Zig's testing capabilities and the meaning of containers.
paulespinosa
force-pushed
the
langref-explain-zig-test-containers
branch
from
fb36d91
to
e01cd46
Compare
This commit updates the Language Reference to explain Zig's testing capabilities and the meaning of containers.
The result is located at the following URLs. They are the two main sections that are new.
https://paulespinosa.github.io/zig-langref/explain-zig-test-and-containers-02.html#Containers
https://paulespinosa.github.io/zig-langref/explain-zig-test-and-containers-02.html#Zig-Test
Issue #8221