Nixyri/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2024-11-15 00:26:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

langref: delete Nested Container Tests section

Browse Source 
This section documented how a buggy feature worked at one point in time
but it's not a description of what is supposed to happen. What is
supposed to happen is simple enough to not warrant any documentation
about it. When a file is imported, all the test decls are supposed to be
queued for analysis.

Also, refAllDecls() is a hack which should not be celebrated or even
mentioned in the language reference.

closes #18042
This commit is contained in:
Andrew Kelley 2024-01-18 19:56:15 -07:00
parent 9b714e019c
commit 9e6ff71330
1 changed files with 0 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
doc/langref.html.in
View File

@ -1173,74 +1173,6 @@ fn addOne(number: i32) i32 {
</p>
{#see_also|The Global Error Set|Grammar#}
{#header_close#}
{#header_open|Nested Container Tests#}
<p>
When the <kbd>zig test</kbd> tool is building a test runner, only resolved {#syntax#}test{#endsyntax#}
declarations are included in the build. Initially, only the given Zig source file's top-level
declarations are resolved. Unless nested {#link|containers|Containers#} are referenced from a top-level test declaration,
nested container tests will not be resolved.
</p>
<p>
The code sample below uses the {#syntax#}std.testing.refAllDecls(@This()){#endsyntax#} function call to
reference all of the containers that are in the file including the imported Zig source file. The code
sample also shows an alternative way to reference containers using the {#syntax#}_ = C;{#endsyntax#}
syntax. This syntax tells the compiler to ignore the result of the expression on the right side of the
assignment operator.
</p>
{#code_begin|test|testing_nested_container_tests#}
const std = @import("std");
const expect = std.testing.expect;
// Imported source file tests will run when referenced from a top-level test declaration.
// The next line alone does not cause "testing_introduction.zig" tests to run.
const imported_file = @import("testing_introduction.zig");
test {
// To run nested container tests, either, call `refAllDecls` which will
// reference all declarations located in the given argument.
// `@This()` is a builtin function that returns the innermost container it is called from.
// In this example, the innermost container is this file (implicitly a struct).
std.testing.refAllDecls(@This());
// or, reference each container individually from a top-level test declaration.
// The `_ = C;` syntax is a no-op reference to the identifier `C`.
_ = S;
_ = U;
_ = @import("testing_introduction.zig");
}
const S = struct {
test "S demo test" {
try expect(true);
}
const SE = enum {
V,
// This test won't run because its container (SE) is not referenced.
test "This Test Won't Run" {
try expect(false);
}
};
};
const U = union { // U is referenced by the file's top-level test declaration
s: US, // and US is referenced here; therefore, "U.Us demo test" will run
const US = struct {
test "U.US demo test" {
// This test is a top-level test declaration for the struct.
// The struct is nested (declared) inside of a union.
try expect(true);
}
};
test "U demo test" {
try expect(true);
}
};
{#code_end#}
{#header_close#}
{#header_open|Test Failure#}
<p>
The default test runner checks for an {#link|error|Errors#} returned from a test.