add documentation for zig test

closes #1518

doc/langref.html.in

@@ -8396,11 +8396,78 @@ const separator = if (builtin.os == builtin.Os.windows) '\\' else '/';
       <p>TODO: using comptime { _ = @import() }</p>
       {#header_close#}
       {#header_open|Zig Test#}
-      <p>TODO: basic usage</p>
-      <p>TODO: lazy analysis</p>
-      <p>TODO: --test-filter</p>
-      <p>TODO: --test-name-prefix</p>
-      <p>TODO: testing in releasefast and releasesafe mode. assert still works</p>
+      <p>
+      <code>zig test</code> is a tool that can be used to quickly build and run Zig code
+      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.
+      </p>
+      {#code_begin|test|detect_test#}
+const std = @import("std");
+const builtin = @import("builtin");
+const assert = std.debug.assert;
+
+test "builtin.is_test" {
+    assert(builtin.is_test);
+}
+      {#code_end#}
+      <p>
+      Zig has lazy top level declaration analysis, which means that if a function is not called,
+      or otherwise used, it is not analyzed. This means that there may be an undiscovered
+      compile error in a function because it is never called.
+      </p>
+      {#code_begin|test|unused_fn#}
+fn unused() i32 {
+    return "wrong return type";
+}
+test "unused function" { }
+      {#code_end#}
+      <p>
+      Note that, while in {#link|Debug#} and {#link|ReleaseSafe#} modes, {#link|unreachable#} emits a
+      call to {#link|@panic#}, in {#link|ReleaseFast#} and {#link|ReleaseSmall#} modes, it is really
+      undefined behavior. The implementation of {#syntax#}std.debug.assert{#endsyntax#} is as
+      simple as:
+      </p>
+      {#code_begin|syntax#}
+pub fn assert(ok: bool) void {
+    if (!ok) unreachable;
+}
+      {#code_end#}
+      <p>
+      This means that when testing in ReleaseFast or ReleaseSmall mode, {#syntax#}assert{#endsyntax#}
+      is not sufficient to check the result of a computation:
+      </p>
+      {#code_begin|test|assert#}
+      {#code_release_fast#}
+const std = @import("std");
+const assert = std.debug.assert;
+
+test "assert in release fast mode" {
+    assert(false);
+}
+      {#code_end#}
+      <p>Note that although the above example shows the test passing, this is invoking
+      unchecked {#link|Undefined Behavior#}. This documentation is showing only one possible
+      outcome of this test.</p>
+      <p>
+      Better practice for checking the output when testing is to use {#syntax#}std.testing.expect{#endsyntax#}:
+      </p>
+      {#code_begin|test_err|test failure#}
+      {#code_release_fast#}
+const std = @import("std");
+const expect = std.testing.expect;
+
+test "assert in release fast mode" {
+    expect(false);
+}
+      {#code_end#}
+      <p>See the rest of the {#syntax#}std.testing{#endsyntax#} namespace for more available functions.</p>
+      <p>
+      <code>zig test</code> has a few command line parameters which affect the compilation. See
+      <code>zig --help</code> for a full list. The most interesting one is <code>--test-filter [text]</code>.
+      This makes the test build only include tests whose name contains the supplied filter text.
+      Again, thanks to lazy analysis, this can allow you to narrow a build to only a few functions in
+      isolation.
+      </p>
       {#header_close#}
       {#header_open|Zig Build System#}
       <p>TODO: explain purpose, it's supposed to replace make/cmake</p>