authorgravatar for noam@pixelhero.devNoam Preil <noam@pixelhero.dev> 2020-06-26 06:51:35-04:00
committergravatar for noam@pixelhero.devNoam Preil <noam@pixelhero.dev> 2020-06-26 06:51:35-04:00
log6d536168b004a56e0cd0748dca8f0e7f0822fdce
tree70dfa0557bee2ae62b062281a9cf58a588a60e9c
parent0e952a9f3a1522a6fd39d67a495d3918b8d8240d
signature Commit is signed but in an unrecognized format.

Stage2/Testing: Update documentation

1 files changed, 64 insertions(+), 23 deletions(-)

src-self-hosted/test.zig+64-23
......@@ -34,7 +34,7 @@ pub const TestContext = struct {
3434 /// effects of the incremental compilation.
3535 src: [:0]const u8,
3636 case: union(enum) {
37 /// A transformation update transforms the input ZIR and tests against
37 /// A transformation update transforms the input and tests against
3838 /// the expected output ZIR.
3939 Transformation: [:0]const u8,
4040 /// An error update attempts to compile bad code, and ensures that it
......@@ -43,6 +43,7 @@ pub const TestContext = struct {
4343 Error: []const ErrorMsg,
4444 /// An execution update compiles and runs the input, testing the
4545 /// stdout against the expected results
46 /// This is a slice containing the expected message.
4647 Execution: []const u8,
4748 },
4849 };
......@@ -56,16 +57,20 @@ pub const TestContext = struct {
5657 /// update, so each update's source is treated as a single file being
5758 /// updated by the test harness and incrementally compiled.
5859 pub const Case = struct {
60 /// The name of the test case. This is shown if a test fails, and
61 /// otherwise ignored.
5962 name: []const u8,
6063 /// The platform the test targets. For non-native platforms, an emulator
6164 /// such as QEMU is required for tests to complete.
6265 target: std.zig.CrossTarget,
66 /// In order to be able to run e.g. Execution updates, this must be set
67 /// to Executable.
6368 output_mode: std.builtin.OutputMode,
6469 updates: std.ArrayList(Update),
6570 @"type": TestType,
6671
67 /// Adds a subcase in which the module is updated with new ZIR, and the
68 /// resulting ZIR is validated.
72 /// Adds a subcase in which the module is updated with `src`, and the
73 /// resulting ZIR is validated against `result`.
6974 pub fn addTransform(self: *Case, src: [:0]const u8, result: [:0]const u8) void {
7075 self.updates.append(.{
7176 .src = src,
......@@ -73,6 +78,8 @@ pub const TestContext = struct {
7378 }) catch unreachable;
7479 }
7580
81 /// Adds a subcase in which the module is updated with `src`, compiled,
82 /// run, and the output is tested against `result`.
7683 pub fn addCompareOutput(self: *Case, src: [:0]const u8, result: []const u8) void {
7784 self.updates.append(.{
7885 .src = src,
......@@ -80,10 +87,10 @@ pub const TestContext = struct {
8087 }) catch unreachable;
8188 }
8289
83 /// Adds a subcase in which the module is updated with invalid ZIR, and
84 /// ensures that compilation fails for the expected reasons.
85 ///
86 /// Errors must be specified in sequential order.
90 /// Adds a subcase in which the module is updated with `src`, which
91 /// should contain invalid input, and ensures that compilation fails
92 /// for the expected reasons, given in sequential order in `errors` in
93 /// the form `:error: line:column: message`.
8794 pub fn addError(self: *Case, src: [:0]const u8, errors: []const []const u8) void {
8895 var array = self.updates.allocator.alloc(ErrorMsg, errors.len) catch unreachable;
8996 for (errors) |e, i| {
......@@ -121,6 +128,8 @@ pub const TestContext = struct {
121128 self.updates.append(.{ .src = src, .case = .{ .Error = array } }) catch unreachable;
122129 }
123130
131 /// Adds a subcase in which the module is updated with `src`, and
132 /// asserts that it compiles without issue
124133 pub fn compiles(self: *Case, src: [:0]const u8) void {
125134 self.addError(src, &[_][]const u8{});
126135 }
......@@ -142,10 +151,12 @@ pub const TestContext = struct {
142151 return &ctx.cases.items[ctx.cases.items.len - 1];
143152 }
144153
154 /// Adds a test case for Zig input, producing an executable
145155 pub fn exe(ctx: *TestContext, name: []const u8, target: std.zig.CrossTarget) *Case {
146156 return ctx.addExe(name, target, .Zig);
147157 }
148158
159 /// Adds a test case for ZIR input, producing an executable
149160 pub fn exeZIR(ctx: *TestContext, name: []const u8, target: std.zig.CrossTarget) *Case {
150161 return ctx.addExe(name, target, .ZIR);
151162 }
......@@ -166,10 +177,12 @@ pub const TestContext = struct {
166177 return &ctx.cases.items[ctx.cases.items.len - 1];
167178 }
168179
180 /// Adds a test case for Zig input, producing an object file
169181 pub fn obj(ctx: *TestContext, name: []const u8, target: std.zig.CrossTarget) *Case {
170182 return ctx.addObj(name, target, .Zig);
171183 }
172184
185 /// Adds a test case for ZIR input, producing an object file
173186 pub fn objZIR(ctx: *TestContext, name: []const u8, target: std.zig.CrossTarget) *Case {
174187 return ctx.addObj(name, target, .ZIR);
175188 }
......@@ -184,6 +197,8 @@ pub const TestContext = struct {
184197 ctx.addExe(name, .{}, T).addCompareOutput(src, expected_stdout);
185198 }
186199
200 /// Adds a test case that compiles the Zig source given in `src`, executes
201 /// it, runs it, and tests the output against `expected_stdout`
187202 pub fn compareOutput(
188203 ctx: *TestContext,
189204 name: []const u8,
......@@ -193,6 +208,8 @@ pub const TestContext = struct {
193208 return ctx.addCompareOutput(name, .Zig, src, expected_stdout);
194209 }
195210
211 /// Adds a test case that compiles the ZIR source given in `src`, executes
212 /// it, runs it, and tests the output against `expected_stdout`
196213 pub fn compareOutputZIR(
197214 ctx: *TestContext,
198215 name: []const u8,
......@@ -213,6 +230,8 @@ pub const TestContext = struct {
213230 ctx.addObj(name, target, T).addTransform(src, result);
214231 }
215232
233 /// Adds a test case that compiles the Zig given in `src` to ZIR and tests
234 /// the ZIR against `result`
216235 pub fn transform(
217236 ctx: *TestContext,
218237 name: []const u8,
......@@ -223,6 +242,8 @@ pub const TestContext = struct {
223242 ctx.addTransform(name, target, .Zig, src, result);
224243 }
225244
245 /// Adds a test case that cleans up the ZIR source given in `src`, and
246 /// tests the resulting ZIR against `result`
226247 pub fn transformZIR(
227248 ctx: *TestContext,
228249 name: []const u8,
......@@ -244,6 +265,9 @@ pub const TestContext = struct {
244265 ctx.addObj(name, target, T).addError(src, expected_errors);
245266 }
246267
268 /// Adds a test case that ensures that the Zig given in `src` fails to
269 /// compile for the expected reasons, given in sequential order in
270 /// `expected_errors` in the form `:error: line:column: message`.
247271 pub fn compileError(
248272 ctx: *TestContext,
249273 name: []const u8,
......@@ -254,6 +278,9 @@ pub const TestContext = struct {
254278 ctx.addError(name, target, .Zig, src, expected_errors);
255279 }
256280
281 /// Adds a test case that ensures that the ZIR given in `src` fails to
282 /// compile for the expected reasons, given in sequential order in
283 /// `expected_errors` in the form `:error: line:column: message`.
257284 pub fn compileErrorZIR(
258285 ctx: *TestContext,
259286 name: []const u8,
......@@ -274,48 +301,62 @@ pub const TestContext = struct {
274301 ctx.addObj(name, target, T).compiles(src);
275302 }
276303
277 pub fn incrementalFailure(
304 /// Adds a test case that asserts that the Zig given in `src` compiles
305 /// without any errors.
306 pub fn compiles(
278307 ctx: *TestContext,
279308 name: []const u8,
280309 target: std.zig.CrossTarget,
281310 src: [:0]const u8,
282 expected_errors: []const []const u8,
283 fixed_src: [:0]const u8,
284311 ) void {
285 var case = ctx.addObj(name, target, .Zig);
286 case.addError(src, expected_errors);
287 case.compiles(fixed_src);
312 ctx.addCompiles(name, target, .Zig, src);
288313 }
289314
290 pub fn incrementalFailureZIR(
315 /// Adds a test case that asserts that the ZIR given in `src` compiles
316 /// without any errors.
317 pub fn compilesZIR(
291318 ctx: *TestContext,
292319 name: []const u8,
293320 target: std.zig.CrossTarget,
294321 src: [:0]const u8,
295 expected_errors: []const []const u8,
296 fixed_src: [:0]const u8,
297322 ) void {
298 var case = ctx.addObj(name, target, .ZIR);
299 case.addError(src, expected_errors);
300 case.compiles(fixed_src);
323 ctx.addCompiles(name, target, .ZIR, src);
301324 }
302325
303 pub fn compiles(
326 /// Adds a test case that first ensures that the Zig given in `src` fails
327 /// to compile for the reasons given in sequential order in
328 /// `expected_errors` in the form `:error: line:column: message`, then
329 /// asserts that fixing the source (updating with `fixed_src`) isn't broken
330 /// by incremental compilation.
331 pub fn incrementalFailure(
304332 ctx: *TestContext,
305333 name: []const u8,
306334 target: std.zig.CrossTarget,
307335 src: [:0]const u8,
336 expected_errors: []const []const u8,
337 fixed_src: [:0]const u8,
308338 ) void {
309 ctx.addCompiles(name, target, .Zig, src);
339 var case = ctx.addObj(name, target, .Zig);
340 case.addError(src, expected_errors);
341 case.compiles(fixed_src);
310342 }
311343
312 pub fn compilesZIR(
344 /// Adds a test case that first ensures that the ZIR given in `src` fails
345 /// to compile for the reasons given in sequential order in
346 /// `expected_errors` in the form `:error: line:column: message`, then
347 /// asserts that fixing the source (updating with `fixed_src`) isn't broken
348 /// by incremental compilation.
349 pub fn incrementalFailureZIR(
313350 ctx: *TestContext,
314351 name: []const u8,
315352 target: std.zig.CrossTarget,
316353 src: [:0]const u8,
354 expected_errors: []const []const u8,
355 fixed_src: [:0]const u8,
317356 ) void {
318 ctx.addCompiles(name, target, .ZIR, src);
357 var case = ctx.addObj(name, target, .ZIR);
358 case.addError(src, expected_errors);
359 case.compiles(fixed_src);
319360 }
320361
321362 fn init() TestContext {