| ... | @@ -8396,11 +8396,78 @@ const separator = if (builtin.os == builtin.Os.windows) '\\' else '/'; | ... | @@ -8396,11 +8396,78 @@ const separator = if (builtin.os == builtin.Os.windows) '\\' else '/'; |
| 8396 | <p>TODO: using comptime { _ = @import() }</p> | 8396 | <p>TODO: using comptime { _ = @import() }</p> |
| 8397 | {#header_close#} | 8397 | {#header_close#} |
| 8398 | {#header_open|Zig Test#} | 8398 | {#header_open|Zig Test#} |
| 8399 | <p>TODO: basic usage</p> | 8399 | <p> |
| 8400 | <p>TODO: lazy analysis</p> | 8400 | <code>zig test</code> is a tool that can be used to quickly build and run Zig code |
| 8401 | <p>TODO: --test-filter</p> | 8401 | to make sure behavior meets expectations. {#syntax#}@import("builtin").is_test{#endsyntax#} |
| 8402 | <p>TODO: --test-name-prefix</p> | 8402 | is available for code to detect whether the current build is a test build. |
| 8403 | <p>TODO: testing in releasefast and releasesafe mode. assert still works</p> | 8403 | </p> |
| | 8404 | {#code_begin|test|detect_test#} |
| | 8405 | const std = @import("std"); |
| | 8406 | const builtin = @import("builtin"); |
| | 8407 | const assert = std.debug.assert; |
| | 8408 | |
| | 8409 | test "builtin.is_test" { |
| | 8410 | assert(builtin.is_test); |
| | 8411 | } |
| | 8412 | {#code_end#} |
| | 8413 | <p> |
| | 8414 | Zig has lazy top level declaration analysis, which means that if a function is not called, |
| | 8415 | or otherwise used, it is not analyzed. This means that there may be an undiscovered |
| | 8416 | compile error in a function because it is never called. |
| | 8417 | </p> |
| | 8418 | {#code_begin|test|unused_fn#} |
| | 8419 | fn unused() i32 { |
| | 8420 | return "wrong return type"; |
| | 8421 | } |
| | 8422 | test "unused function" { } |
| | 8423 | {#code_end#} |
| | 8424 | <p> |
| | 8425 | Note that, while in {#link|Debug#} and {#link|ReleaseSafe#} modes, {#link|unreachable#} emits a |
| | 8426 | call to {#link|@panic#}, in {#link|ReleaseFast#} and {#link|ReleaseSmall#} modes, it is really |
| | 8427 | undefined behavior. The implementation of {#syntax#}std.debug.assert{#endsyntax#} is as |
| | 8428 | simple as: |
| | 8429 | </p> |
| | 8430 | {#code_begin|syntax#} |
| | 8431 | pub fn assert(ok: bool) void { |
| | 8432 | if (!ok) unreachable; |
| | 8433 | } |
| | 8434 | {#code_end#} |
| | 8435 | <p> |
| | 8436 | This means that when testing in ReleaseFast or ReleaseSmall mode, {#syntax#}assert{#endsyntax#} |
| | 8437 | is not sufficient to check the result of a computation: |
| | 8438 | </p> |
| | 8439 | {#code_begin|test|assert#} |
| | 8440 | {#code_release_fast#} |
| | 8441 | const std = @import("std"); |
| | 8442 | const assert = std.debug.assert; |
| | 8443 | |
| | 8444 | test "assert in release fast mode" { |
| | 8445 | assert(false); |
| | 8446 | } |
| | 8447 | {#code_end#} |
| | 8448 | <p>Note that although the above example shows the test passing, this is invoking |
| | 8449 | unchecked {#link|Undefined Behavior#}. This documentation is showing only one possible |
| | 8450 | outcome of this test.</p> |
| | 8451 | <p> |
| | 8452 | Better practice for checking the output when testing is to use {#syntax#}std.testing.expect{#endsyntax#}: |
| | 8453 | </p> |
| | 8454 | {#code_begin|test_err|test failure#} |
| | 8455 | {#code_release_fast#} |
| | 8456 | const std = @import("std"); |
| | 8457 | const expect = std.testing.expect; |
| | 8458 | |
| | 8459 | test "assert in release fast mode" { |
| | 8460 | expect(false); |
| | 8461 | } |
| | 8462 | {#code_end#} |
| | 8463 | <p>See the rest of the {#syntax#}std.testing{#endsyntax#} namespace for more available functions.</p> |
| | 8464 | <p> |
| | 8465 | <code>zig test</code> has a few command line parameters which affect the compilation. See |
| | 8466 | <code>zig --help</code> for a full list. The most interesting one is <code>--test-filter [text]</code>. |
| | 8467 | This makes the test build only include tests whose name contains the supplied filter text. |
| | 8468 | Again, thanks to lazy analysis, this can allow you to narrow a build to only a few functions in |
| | 8469 | isolation. |
| | 8470 | </p> |
| 8404 | {#header_close#} | 8471 | {#header_close#} |
| 8405 | {#header_open|Zig Build System#} | 8472 | {#header_open|Zig Build System#} |
| 8406 | <p>TODO: explain purpose, it's supposed to replace make/cmake</p> | 8473 | <p>TODO: explain purpose, it's supposed to replace make/cmake</p> |
Andrew Kelley <andrew@ziglang.org> 2019-03-20 23:49:35-04:00
Commit is signed but in an unrecognized format.