From 528079a96c2acaa194ba66e028d3b9b04957b9c7 Mon Sep 17 00:00:00 2001
From: Yves Biener <yves.biener@gmx.de>
Date: Tue, 25 Feb 2025 19:01:36 +0100
Subject: [PATCH] add(testing): how to create zon test files and use them for
 regression testing

---
 Testing.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/Testing.md b/Testing.md
index d18c15d..cc28fe3 100644
--- a/Testing.md
+++ b/Testing.md
@@ -3,3 +3,63 @@
 Using a different testing renderer (in a corresponding namespace `zterm.testing`) renderes without flushing to the screen, but keeps the corresponding `zterm.Cell` slice for comparison. The main question would rather be how to provide the expected value for the `zterm.Cell` slice.
 
 The test renderer shall be configured with a given size (as the corresponding terminal for the screen size will not be available). This serves two aspects: Firstly, `.resize` Event triggering and secondly, the rendering into a `zterm.Cell` slice with the provided size dimensions (for testing layout handling and rendering (i.e. of a scrollable element, etc.)).
+
+For testing `Container`s and/or `Element`s content generation the correspondingly rendered `Cell` slices are tested. For this the test creation is two steped. The first step is the creation of the `.zon` file which contains the expected `Cell` slice for the screen you want to test (you can also test multiple screens - which would be necessary when testing for interactivity). Secondly you create the test case now against the created `.zon` file.
+
+## Zon Test file creation
+
+```zig
+test "create container zon file" {
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(std.testing.allocator, .{
+        .border = .{
+            .color = .green,
+            .sides = .horizontal,
+        },
+    }, .{});
+    defer container.deinit();
+
+    const size: Size = .{
+        .rows = 20,
+        .cols = 30,
+    };
+
+    // NOTE: this is dependent on the working directory the test will be executed in
+    const file = try std.fs.cwd().createFile("src/test/<path>.zon", .{ .truncate = true });
+    defer file.close();
+
+    const allocator = std.testing.allocator;
+    var renderer: testing.Renderer = .init(allocator, size);
+    defer renderer.deinit();
+
+    try container.handle(.{ .resize = size });
+    try renderer.render(Container(event.SystemEvent), &container);
+    try renderer.save(file.writer());
+}
+```
+
+After running the test as usual you created the `<path>.zon` file accordingly in the specified directory. Afterwards you can create the test against that file and the test above should be replaced with the test below.
+
+## Test against zon file
+
+```zig
+test "test container against zon file" {
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(std.testing.allocator, .{
+        .border = .{
+            .color = .green,
+            .sides = .horizontal,
+        },
+    }, .{});
+    defer container.deinit();
+
+    try testing.expectContainerScreen(.{
+        .rows = 20,
+        .cols = 30,
+    }, &container, @import("test/<path>.zon"));
+}
+```