pgtest: import interface spec from go-bits/easypg

This is only based on looking at the API documentation.
As always, the implementation will be completely fresh.

3 files changed, 85 insertions, 0 deletions

diff --git a/README.md b/README.md
index 2a2ad6e..3a7354b 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ My personal extension of the standard library.
 
 - [gsql](./gsql/): abstraction layer for database libraries, supporting both database/sql drivers and non-standard drivers like [pgx](https://github.com/jackc/pgx)
 - [pgruntime](./pgruntime/): connection handling for PostgreSQL databases, including optional support for database migrations and self-contained test DB instances
+- [pgtest](./pgtest/): test assertions for the content of PostgreSQL databases
 
 ### Addons for errors
 
diff --git a/pgtest/snapshot.go b/pgtest/snapshot.go
new file mode 100644
index 0000000..f27ecec
--- /dev/null
+++ b/pgtest/snapshot.go
@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
+// SPDX-License-Identifier: Apache-2.0
+
+package pgtest
+
+import (
+	"fmt"
+
+	"go.xyrillian.de/gg/assert"
+)
+
+// Snapshot contains a set of SQL statements.
+// Instances are produced by methods of [Tracker].
+type Snapshot struct {
+	t assert.TestingTB
+}
+
+// AssertEmpty is a shorthand for AssertEqual("").
+func (s Snapshot) AssertEmpty() {
+	s.t.Helper()
+	s.AssertEqual("")
+}
+
+// AssertEqual compares the set of SQL statements to those in the given string literal.
+// A test error is generated for each difference.
+//
+// This assertion is lenient with regards to whitespace to enable callers
+// to format their string literals in a way that fits nicely in the surrounding code:
+//   - Leading whitespace on each line is ignored.
+//   - Empty lines (containing only whitespace) are ignored.
+func (s Snapshot) AssertEqual(expected string) {
+	s.t.Helper()
+	panic("TODO")
+}
+
+// AssertEqualf is a shorthand for AssertEqual(fmt.Sprintf(format, args...)).
+func (s Snapshot) AssertEqualf(format string, args ...any) {
+	s.t.Helper()
+	s.AssertEqual(fmt.Sprintf(format, args...))
+}
+
+// Ignore is a no-op. It is commonly used like `tr.DBChanges().Ignore()`,
+// to clarify that a certain set of DB changes is not asserted on.
+func (s Snapshot) Ignore() {
+	// intentionally empty
+}
diff --git a/pgtest/tracker.go b/pgtest/tracker.go
new file mode 100644
index 0000000..ebd53cd
--- /dev/null
+++ b/pgtest/tracker.go
@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// Package pgtest contains test assertions for checking the contents of PostgreSQL databases.
+package pgtest
+
+import (
+	"go.xyrillian.de/gg/assert"
+	"go.xyrillian.de/gg/gsql"
+)
+
+// Tracker keeps a copy of the database contents and allows for checking the database contents (or changes made to them) during tests.
+type Tracker struct {
+	t   assert.TestingTB
+	dbh gsql.Handle
+	s   Snapshot
+}
+
+// NewTracker creates a new Tracker.
+//
+// The initial creation involves taking a snapshot, which is returned as a second value.
+// This is an optimization, since it is often desirable to assert on the full DB contents when creating the tracker.
+// Calling [Tracker.DBContent] directly after [NewTracker] would take a superfluous second snapshot.
+func NewTracker(t assert.TestingTB, db gsql.Handle) (*Tracker, Snapshot) {
+	panic("TODO")
+}
+
+// DBChanges produces a diff of the current database contents against the state at the last Tracker call,
+// as a set of INSERT/UPDATE/DELETE statements on which test assertions can be executed.
+func (t *Tracker) DBChanges() Snapshot {
+	panic("TODO")
+}
+
+// DBContent produces a dump of the current database contents,
+// as a sequence of INSERT statements on which test assertions can be executed.
+func (t *Tracker) DBContent() Snapshot {
+	panic("TODO")
+}