authorgravatar for mrpaul@aestheticwisdom.comMr. Paul <mrpaul@aestheticwisdom.com> 2021-07-06 09:59:28+07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2021-07-08 14:33:53-04:00
loga201d80253c79bd6a024cc3dfdad803570fe6c3b
tree95dd5dd03d12716e3a040cce12e9c2e2a15e6b9d
parentec36ac8b21fa6c6d8514c60555aba8a96490a560

Introduce Zig Test earlier in Language Reference

The "Zig Test" section of the language reference has been moved between the current "Hello World" section and the "Comments" section. This was done to introduce the Zig test syntax before it is used in later sections. The description of the Zig test feature has NOT been updated in this commit. Closes #5837

1 files changed, 76 insertions(+), 76 deletions(-)

doc/langref.html.in+76-76
......@@ -344,6 +344,82 @@ pub fn main() void {
344344 </p>
345345 {#see_also|Values|@import|Errors|Root Source File|Source Encoding#}
346346 {#header_close#}
347 {#header_open|Zig Test#}
348 <p>
349 <code>zig test</code> is a tool that can be used to quickly build and run Zig code
350 to make sure behavior meets expectations. {#syntax#}@import("builtin").is_test{#endsyntax#}
351 is available for code to detect whether the current build is a test build.
352 </p>
353 {#code_begin|test|detect_test#}
354const std = @import("std");
355const builtin = @import("builtin");
356const expect = std.testing.expect;
357
358test "builtin.is_test" {
359 try expect(builtin.is_test);
360}
361 {#code_end#}
362 <p>
363 Zig has lazy top level declaration analysis, which means that if a function is not called,
364 or otherwise used, it is not analyzed. This means that there may be an undiscovered
365 compile error in a function because it is never called.
366 </p>
367 {#code_begin|test|unused_fn#}
368fn unused() i32 {
369 return "wrong return type";
370}
371test "unused function" { }
372 {#code_end#}
373 <p>
374 Note that, while in {#link|Debug#} and {#link|ReleaseSafe#} modes, {#link|unreachable#} emits a
375 call to {#link|@panic#}, in {#link|ReleaseFast#} and {#link|ReleaseSmall#} modes, it is really
376 undefined behavior. The implementation of {#syntax#}std.debug.assert{#endsyntax#} is as
377 simple as:
378 </p>
379 {#code_begin|syntax#}
380pub fn assert(ok: bool) void {
381 if (!ok) unreachable;
382}
383 {#code_end#}
384 <p>
385 This means that when testing in ReleaseFast or ReleaseSmall mode, {#syntax#}assert{#endsyntax#}
386 is not sufficient to check the result of a computation:
387 </p>
388 {#code_begin|syntax#}
389const std = @import("std");
390const assert = std.debug.assert;
391
392test "assert in release fast mode" {
393 assert(false);
394}
395 {#code_end#}
396 <p>
397 When compiling this test in {#link|ReleaseFast#} mode, it invokes unchecked
398 {#link|Undefined Behavior#}. Since that could do anything, this documentation
399 cannot show you the output.
400 </p>
401 <p>
402 Better practice for checking the output when testing is to use {#syntax#}std.testing.expect{#endsyntax#}:
403 </p>
404 {#code_begin|test_err|test "expect in release fast mode"... FAIL (TestUnexpectedResult)#}
405 {#code_release_fast#}
406const std = @import("std");
407const expect = std.testing.expect;
408
409test "expect in release fast mode" {
410 try expect(false);
411}
412 {#code_end#}
413 <p>See the rest of the {#syntax#}std.testing{#endsyntax#} namespace for more available functions.</p>
414 <p>
415 <code>zig test</code> has a few command line parameters which affect the compilation. See
416 <code>zig --help</code> for a full list. The most interesting one is <code>--test-filter [text]</code>.
417 This makes the test build only include tests whose name contains the supplied filter text.
418 Again, thanks to lazy analysis, this can allow you to narrow a build to only a few functions in
419 isolation.
420 </p>
421 {#header_close#}
422
347423 {#header_open|Comments#}
348424 {#code_begin|test|comments#}
349425const expect = @import("std").testing.expect;
......@@ -9725,82 +9801,6 @@ const separator = if (builtin.os.tag == builtin.Os.windows) '\\' else '/';
97259801 <p>TODO: lazy analysis</p>
97269802 <p>TODO: using comptime { _ = @import() }</p>
97279803 {#header_close#}
9728 {#header_open|Zig Test#}
9729 <p>
9730 <code>zig test</code> is a tool that can be used to quickly build and run Zig code
9731 to make sure behavior meets expectations. {#syntax#}@import("builtin").is_test{#endsyntax#}
9732 is available for code to detect whether the current build is a test build.
9733 </p>
9734 {#code_begin|test|detect_test#}
9735const std = @import("std");
9736const builtin = @import("builtin");
9737const expect = std.testing.expect;
9738
9739test "builtin.is_test" {
9740 try expect(builtin.is_test);
9741}
9742 {#code_end#}
9743 <p>
9744 Zig has lazy top level declaration analysis, which means that if a function is not called,
9745 or otherwise used, it is not analyzed. This means that there may be an undiscovered
9746 compile error in a function because it is never called.
9747 </p>
9748 {#code_begin|test|unused_fn#}
9749fn unused() i32 {
9750 return "wrong return type";
9751}
9752test "unused function" { }
9753 {#code_end#}
9754 <p>
9755 Note that, while in {#link|Debug#} and {#link|ReleaseSafe#} modes, {#link|unreachable#} emits a
9756 call to {#link|@panic#}, in {#link|ReleaseFast#} and {#link|ReleaseSmall#} modes, it is really
9757 undefined behavior. The implementation of {#syntax#}std.debug.assert{#endsyntax#} is as
9758 simple as:
9759 </p>
9760 {#code_begin|syntax#}
9761pub fn assert(ok: bool) void {
9762 if (!ok) unreachable;
9763}
9764 {#code_end#}
9765 <p>
9766 This means that when testing in ReleaseFast or ReleaseSmall mode, {#syntax#}assert{#endsyntax#}
9767 is not sufficient to check the result of a computation:
9768 </p>
9769 {#code_begin|syntax#}
9770const std = @import("std");
9771const assert = std.debug.assert;
9772
9773test "assert in release fast mode" {
9774 assert(false);
9775}
9776 {#code_end#}
9777 <p>
9778 When compiling this test in {#link|ReleaseFast#} mode, it invokes unchecked
9779 {#link|Undefined Behavior#}. Since that could do anything, this documentation
9780 cannot show you the output.
9781 </p>
9782 <p>
9783 Better practice for checking the output when testing is to use {#syntax#}std.testing.expect{#endsyntax#}:
9784 </p>
9785 {#code_begin|test_err|test "expect in release fast mode"... FAIL (TestUnexpectedResult)#}
9786 {#code_release_fast#}
9787const std = @import("std");
9788const expect = std.testing.expect;
9789
9790test "expect in release fast mode" {
9791 try expect(false);
9792}
9793 {#code_end#}
9794 <p>See the rest of the {#syntax#}std.testing{#endsyntax#} namespace for more available functions.</p>
9795 <p>
9796 <code>zig test</code> has a few command line parameters which affect the compilation. See
9797 <code>zig --help</code> for a full list. The most interesting one is <code>--test-filter [text]</code>.
9798 This makes the test build only include tests whose name contains the supplied filter text.
9799 Again, thanks to lazy analysis, this can allow you to narrow a build to only a few functions in
9800 isolation.
9801 </p>
9802 {#header_close#}
9803
98049804 {#header_open|Zig Build System#}
98059805 <p>
98069806 The Zig Build System provides a cross-platform, dependency-free way to declare