Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Zig documentation should have more information about test syntax #8221

Open
finleyjb opened this issue Mar 12, 2021 · 4 comments
Open

Zig documentation should have more information about test syntax #8221

finleyjb opened this issue Mar 12, 2021 · 4 comments
Labels
contributor friendly This issue is limited in scope and/or knowledge of Zig internals. docs enhancement Solving this issue will likely involve adding new logic or components to the codebase.
Milestone
1.0.0

Comments

@finleyjb
Copy link

I see Zig's testing mechanisms used quite extensively throughout the zig website, but the only place I see that documents anything about it is buried here. It would be really helpful if this were documented more prominently. How does the syntax work? What can I do with the testing framework?

That would really be nice because not only does it help me understand the rest of zig's documentation better, but because I see the ability to have tests in the same file as your code to be a killer feature.
@jclark
Copy link

jclark commented Mar 12, 2021

I was confused by this too. Specifically here: https://ziglang.org/documentation/0.7.1/#Comments

The first Hello World example is explained beautifully. The second example uses the syntax test string { block }, but does not explain what the semantics of this is. Even the "Zig Test" section doesn't really explain this. How exactly does a top-level test block differ from a function definition? For example, am I allowed to use try in it?

@SpexGuy SpexGuy added docs enhancement Solving this issue will likely involve adding new logic or components to the codebase. contributor friendly This issue is limited in scope and/or knowledge of Zig internals. labels Mar 12, 2021
@finleyjb finleyjb mentioned this issue Mar 13, 2021
Closed
@Mouvedia Mouvedia mentioned this issue Mar 25, 2021
Closed
@andrewrk andrewrk added this to the 1.0.0 milestone May 19, 2021
@paulespinosa paulespinosa mentioned this issue Sep 11, 2021
Closed
paulespinosa added a commit to paulespinosa/zig that referenced this issue Sep 29, 2021
@paulespinosa
langref: Explain Zig Test
ac9ce64 
Updates the Language Reference sections: Comments, Values, and Zig Test.

Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue ziglang#1524).

Comments and Values section examples changed test declarations to a main
function and expect statement to print statments.

A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.

Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.

Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, and reference.

GitHub Issues: ziglang#8221, ziglang#8234
@paulespinosa paulespinosa mentioned this issue Sep 29, 2021
Merged
@paulespinosa
Copy link
Contributor

@finjo-the-great @jclark if you're still around, does #9858 answer your questions and concerns?

@jclark
Copy link

jclark commented Sep 29, 2021

@paulespinosa Yes, that is very helpful.

paulespinosa added a commit to paulespinosa/zig that referenced this issue Sep 29, 2021
@paulespinosa
langref: Explain Zig Test
e9ec474 
Updates the Language Reference sections: Comments, Values, and Zig Test.

Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue ziglang#1524).

Comments and Values section examples changed test declarations to a main
function and expect statement to print statements.

A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.

Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.

Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, reference.

GitHub Issues: ziglang#8221, ziglang#8234
paulespinosa added a commit to paulespinosa/zig that referenced this issue Sep 29, 2021
@paulespinosa
langref: Explain Zig Test
eeea9a6 
Updates the Language Reference sections: Comments, Values, and Zig Test.

Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue ziglang#1524).

Comments and Values section examples changed test declarations to a main
function and expect statement to print statements.

A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.

Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.

Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, reference.

GitHub Issues: ziglang#8221, ziglang#8234
paulespinosa added a commit to paulespinosa/zig that referenced this issue Sep 30, 2021
@paulespinosa
langref: Explain Zig Test
04a72a4 
Updates the Language Reference sections: Comments, Values, and Zig Test.

Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue ziglang#1524).

Comments and Values section examples changed test declarations to a main
function and expect statement to print statements.

A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.

Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.

Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, reference.

GitHub Issues: ziglang#8221, ziglang#8234
paulespinosa added a commit to paulespinosa/zig that referenced this issue Sep 30, 2021
@paulespinosa
langref: Explain Zig Test
ee04b58 
Updates the Language Reference sections: Comments, Values, and Zig Test.

Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue ziglang#1524).

Comments and Values section examples changed test declarations to a main
function and expect statement to print statements.

A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.

Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.

Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, reference.

GitHub Issues: ziglang#8221, ziglang#8234
andrewrk pushed a commit that referenced this issue Oct 4, 2021
@paulespinosa @andrewrk
langref: Explain Zig Test
65e4926 
Updates the Language Reference sections: Comments, Values, and Zig Test.

Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue #1524).

Comments and Values section examples changed test declarations to a main
function and expect statement to print statements.

A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.

Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.

Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, reference.

GitHub Issues: #8221, #8234
@depperm
Copy link

depperm commented Aug 4, 2023

so should this be closed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
contributor friendly This issue is limited in scope and/or knowledge of Zig internals. docs enhancement Solving this issue will likely involve adding new logic or components to the codebase.
Projects
None yet
Milestone
1.0.0
Development

No branches or pull requests
6 participants
@andrewrk @jclark @SpexGuy @paulespinosa @depperm @finleyjb