Adding mimicry (internal mock mechanism)

Mimicry is a lightweight, zero dependency mock mechanism created to ease testing of Tigron.
Since Tigron heavily relies on *testing.T, it is currently hard to test.
Moving away to a tig.T interface instead of *testing.T will unlock the ability to mock.
Mimicry does provide:
- recording of all function calls, with arguments and complete stack trace (see Report())
- optional custom handling of function calls (see Register())
- QOL: fancyfied OCS8 links allow opening files from traces in terminal

UX is largely in flux right now and experimental, but the objective is to:
- do not require code generation
- do not abuse reflection
- keep the amount of boilerplate to the absolute minimum for the mock consumer
- ... and as small as possible for the mock creator
- keep zero dependencies

This commit also introduce the tig.T interface to be used everywhere inside Tigron in the future,
along with a complete mock for it.

Mimicry is not meant to be used directly for now, though, if there is interest, a future
version might graduate out of `internal`.

Signed-off-by: apostasie <[email protected]>

Author: apostasie

mod/tigron/internal/formatter/doc.go

@@ -0,0 +1,18 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+// Package formatter provides simple formatting helpers for internal consumption.
+package formatter

mod/tigron/internal/formatter/formatter.go

@@ -0,0 +1,95 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package formatter
+
+import (
+	"fmt"
+	"strings"
+	"unicode/utf8"
+)
+
+const (
+	maxLineLength = 110
+	maxLines      = 100
+	kMaxLength    = 7
+)
+
+func chunk(s string, length int) []string {
+	var chunks []string
+
+	lines := strings.Split(s, "\n")
+
+	for x := 0; x < maxLines && x < len(lines); x++ {
+		line := lines[x]
+		if utf8.RuneCountInString(line) < length {
+			chunks = append(chunks, line)
+
+			continue
+		}
+
+		for index := 0; index < utf8.RuneCountInString(line); index += length {
+			end := index + length
+			if end > utf8.RuneCountInString(line) {
+				end = utf8.RuneCountInString(line)
+			}
+
+			chunks = append(chunks, string([]rune(line)[index:end]))
+		}
+	}
+
+	if len(chunks) == maxLines {
+		chunks = append(chunks, "...")
+	}
+
+	return chunks
+}
+
+// Table formats a `n x 2` dataset into a series of rows.
+// FIXME: the problem with full-width emoji is that they are going to eff-up the maths and display
+// here...
+// Maybe the csv writer could be cheat-used to get the right widths.
+//
+//nolint:mnd // Too annoying
+func Table(data [][]any) string {
+	var output string
+
+	for _, row := range data {
+		key := fmt.Sprintf("%v", row[0])
+		value := strings.ReplaceAll(fmt.Sprintf("%v", row[1]), "\t", "  ")
+
+		output += fmt.Sprintf("+%s+\n", strings.Repeat("-", maxLineLength-2))
+
+		if utf8.RuneCountInString(key) > kMaxLength {
+			key = string([]rune(key)[:kMaxLength-3]) + "..."
+		}
+
+		for _, line := range chunk(value, maxLineLength-kMaxLength-7) {
+			output += fmt.Sprintf(
+				"| %-*s | %-*s |\n",
+				kMaxLength,
+				key,
+				maxLineLength-kMaxLength-7,
+				line,
+			)
+			key = ""
+		}
+	}
+
+	output += fmt.Sprintf("+%s+", strings.Repeat("-", maxLineLength-2))
+
+	return output
+}

mod/tigron/internal/formatter/osc8.go

@@ -0,0 +1,31 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package formatter
+
+import "fmt"
+
+// OSC8 hyperlinks implementation.
+type OSC8 struct {
+	Location string `json:"location"`
+	Line     int    `json:"line"`
+	Text     string `json:"text"`
+}
+
+func (o *OSC8) String() string {
+	// FIXME: not sure if any desktop software does support line numbers anchors?
+	return fmt.Sprintf("\x1b]8;;%s#%d:1\x07%s\x1b]8;;\x07"+"\u001b[0m", o.Location, o.Line, o.Text)
+}

mod/tigron/internal/mimicry/doc.go

@@ -0,0 +1,21 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+// Package mimicry provides a very rough and rudimentary mimicry library to help with internal tigron testing.
+// It does not require generation, does not abuse reflect (too much), and keeps the amount of boilerplate baloney to a
+// minimum.
+// This is NOT a generic mock library. Use something else if you need one.
+package mimicry

mod/tigron/internal/mimicry/doc.md

@@ -0,0 +1,118 @@
+# [INTERNAL] [EXPERIMENTAL] Mimicry
+
+## Creating a Mock
+
+```golang
+package mymock
+
+import "github.com/containerd/nerdctl/mod/tigron/internal/mimicry"
+
+// Let's assume we want to mock the following, likely defined somewhere else
+// type InterfaceToBeMocked interface {
+//    SomeMethod(one string, two int) error
+// }
+
+// Compile time ensure the mock does fulfill the interface
+var _ InterfaceToBeMocked = &MyMock{}
+
+type MyMock struct {
+    // Embed mimicry core
+	mimicry.Core
+}
+
+// First, describe function parameters and return values.
+type (
+    MyMockSomeMethodIn struct {
+        one string
+        two int
+    }
+
+    MyMockSomeMethodOut = error
+)
+
+// Satisfy the interface + wire-in the handler mechanism
+
+func (m *MyMock) SomeMethod(one string, two int) error {
+	// Call mimicry method Retrieve that will record the call, and return a custom handler if one is defined
+    if handler := m.Retrieve(); handler != nil {
+		// Call the optional handler if there is one.
+        return handler.(mimicry.Function[MyMockSomeMethodIn, MyMockSomeMethodOut])(MyMockSomeMethodIn{
+            one: one,
+            two: two,
+        })
+    }
+
+    return nil
+}
+```
+
+
+## Using a Mock
+
+For consumers, the simplest way to use the mock is to inspect calls after the fact:
+
+```golang
+package mymock
+
+import "testing"
+
+// This is the code you want to test, that does depend on the interface we are mocking.
+// func functionYouWantToTest(o InterfaceToBeMocked, i int) {
+//    o.SomeMethod("lala", i)
+// }
+
+func TestOne(t *testing.T) {
+	// Create the mock from above
+    mocky := &MyMock{}
+
+	// Call the function you want to test
+    functionYouWantToTest(mocky, 42)
+    functionYouWantToTest(mocky, 123)
+
+    // Now you can inspect the calls log for that function.
+    report := mocky.Report(InterfaceToBeMocked.SomeMethod)
+    t.Log("Number of times it was called:", len(report))
+    t.Log("Inspecting the last call:")
+    t.Log(mimicry.PrintCall(report[len(report)-1]))
+}
+```
+
+## Using handlers
+
+Implementing handlers allows active interception of the calls for more elaborate scenarios.
+
+```golang
+package main_test
+
+import "testing"
+
+// The method you want to test against the mock
+// func functionYouWantToTest(o InterfaceToBeMocked, i int) {
+//    o.SomeMethod("lala", i)
+// }
+
+func TestTwo(t *testing.T) {
+	// Create the base mock
+    mocky := &MyMock{}
+
+	// Declare a custom handler for the method `SomeMethod`
+    mocky.Register(InterfaceToBeMocked.SomeMethod, func(in MyMockSomeMethodIn) MyMockSomeMethodOut {
+        t.Log("Got parameters", in)
+
+        // We want to fail on that
+        if in.two == 42 {
+            // Print out the callstack
+            report := mocky.Report(InterfaceToBeMocked.SomeMethod)
+            t.Log(mimicry.PrintCall(report[len(report)-1]))
+            t.Error("We do not want to ever receive 42. Inspect trace above.")
+        }else{
+            t.Log("all fine - we did not see 42")
+        }
+
+        return nil
+    })
+
+    functionYouWantToTest(mocky, 123)
+    functionYouWantToTest(mocky, 42)
+}
+```