docs: add README files for poutine, testine, mongodb driver with detailed usage and features

Author: calumari

README.md

@@ -1 +1,110 @@
-# poutine
+# poutine
+
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.25-blue.svg)](https://golang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Go Report Card](https://goreportcard.com/badge/github.com/calumari/poutine)](https://goreportcard.com/report/github.com/calumari/poutine)
+
+A Go library for database integration testing using JSON fixtures and snapshot assertions.
+
+## Packages
+
+* **`poutine`** – Core library providing a database-agnostic testing interface.
+* **`database/mongodb`** – MongoDB driver implementation.
+* **`testine`** – Utilities for loading fixtures, capturing snapshots, and cleaning up.
+
+## Overview
+
+Database integration tests can be tricky - like trying to eat poutine with a spoon. This library helps you **put in** your test data cleanly:
+
+* Version-controlled JSON fixtures for consistent test data
+* Snapshot assertions to compare current database state with expected data  
+* Handling of generated values like ObjectIDs and timestamps
+* Clean teardown so you don't leave a mess behind
+* Automatic cleanup of test data
+* Support for multiple backends through a driver interface
+
+The goal is to reduce boilerplate and make test code easier to read and maintain, without adding extra complexity.
+
+## Install
+
+```bash
+go get github.com/calumari/poutine
+# Optional MongoDB driver
+go get github.com/calumari/poutine/database/mongodb
+```
+
+## Quick Start (MongoDB)
+
+```go
+package mytest
+
+import (
+	"testing"
+
+	"github.com/calumari/poutine"
+	"github.com/calumari/poutine/database/mongodb"
+	"github.com/calumari/poutine/testine"
+)
+
+func Test_UserFlow(t *testing.T) {
+	// Acquire a *mongo.Database instance
+	pt := poutine.New(mongodb.NewDriver(db))
+	ti, err := testine.New(pt)
+	if err != nil { 
+		t.Fatalf("failed to create test helper: %v", err) 
+	}
+	ti.Cleanup(t) // register teardown
+
+	// Seed DB from a JSON fixture
+	snap := ti.Seed(t, ti.LoadJSON(t, "testdata/seed.json"))
+
+	// ... run code that modifies the database ...
+	snap.Assert(t) // check expected state
+
+	// Or compare against a specific expected state
+	ti.Assert(t, ti.LoadJSON(t, "testdata/after.json"))
+}
+```
+
+## JSON Fixture Format
+
+JSON fixtures are objects with collection (or table) names as keys and arrays of documents as values:
+
+```jsonc
+{
+	"users": [
+		{"_id": {"$oid": true}, "email": "[email protected]"},
+		{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "email": "[email protected]"}
+	],
+	"pets": [
+		{"name": "Fido", "ownerEmail": "[email protected]"}
+	]
+}
+```
+
+* `{"$oid": true}` – matches any ObjectID (wildcard)
+* `{"$oid": "hex_string"}` – matches a specific ObjectID
+
+## Using `testine`
+
+`testine.T` wraps a `Poutine` instance and provides helper methods:
+
+* `Seed(t, doc) *Snapshot` – seed DB and capture snapshot
+* `Assert(t, expectedDoc)` – compare current DB state to expected
+* `Snapshot.Assert(t)` – compare current state to previously captured snapshot
+* `Cleanup(t)` – register teardown
+* `LoadJSON(t, path|glob|dir)` – load JSON from file, directory, or glob; supports caching with `testine.WithDocumentCache()`
+
+## Custom Drivers
+
+Implement the `database.Driver` interface to support new databases:
+
+```go
+type Driver interface {
+    Seed(ctx context.Context, root jwalk.Document) (jwalk.Document, error)
+    Snapshot(ctx context.Context) (jwalk.Document, error)
+    Teardown(ctx context.Context) error
+}
+```
+
+See [`database/mongodb/driver.go`](database/mongodb/driver.go) for a reference implementation.

database/mongodb/README.md

@@ -0,0 +1,56 @@
+# poutine MongoDB Driver
+
+MongoDB driver for the poutine testing library.
+
+## Features
+
+* Bulk insert operations for test data seeding
+* Database snapshot capture as JSON documents
+* ObjectID handling with `$oid` directives (wildcard or exact match)
+* Built on the official [MongoDB v2 Go driver](https://github.com/mongodb/mongo-go-driver)
+
+## Install
+
+```bash
+go get github.com/calumari/poutine/database/mongodb
+```
+
+## Usage
+
+Get started with familiar MongoDB patterns:
+
+```go
+import (
+    "testing"
+
+    "github.com/calumari/poutine"
+    "github.com/calumari/poutine/database/mongodb"
+    "github.com/calumari/poutine/testine"
+)
+
+func Test_Something(t *testing.T) {
+    // db is your *mongo.Database instance
+    pt := poutine.New(mongodb.NewDriver(db))
+    ti, err := testine.New(pt)
+    if err != nil { t.Fatalf("failed to create test helper: %v", err) }
+    ti.Cleanup(t)
+    // ... mutate DB ...
+    ti.Assert(t, ti.LoadJSON(t, "testdata/expected.json"))
+}
+```
+
+## ObjectID Handling
+
+Use `$oid` in JSON documents to represent MongoDB ObjectIDs:
+
+```json
+{
+  "users": [
+    {"_id": {"$oid": true}, "email": "[email protected]"},           // wildcard: any ObjectID
+    {"_id": {"$oid": "507f1f77bcf86cd799439011"}, "email": "[email protected]"}  // exact match
+  ]
+}
+```
+
+* `{"$oid": true}` – matches any valid ObjectID
+* `{"$oid": "hex_string"}` – matches a specific ObjectID

testine/README.md

@@ -0,0 +1,45 @@
+# testine
+
+Testine provides helper APIs for seeding databases, capturing snapshots, and making assertions, helping reduce repetitive test setup.
+
+## Features
+
+* Load JSON fixture files from paths, glob patterns, or directories
+* Optional document caching to avoid re-parsing fixtures in subtests
+* Convenience methods for seeding, snapshotting, and assertions
+* Integration with [`testequals`](https://github.com/calumari/testequals/) for rich diffs
+
+## Usage
+
+```go
+func Test_Something(t *testing.T) {
+    pt := poutine.New(mongodb.NewDriver(db))
+    ti, err := testine.New(pt)
+    if err != nil { t.Fatalf("failed to create test helper: %v", err) }
+    ti.Cleanup(t) // cleanup after test
+
+    // seed database from a fixture
+    snap := ti.Seed(t, ti.LoadJSON(t, "testdata/seed.json"))
+
+    // ... run code that modifies database ...
+    snap.Assert(t) // assert no unintended mutations
+    // or assert against a specific expected state
+    ti.Assert(t, ti.LoadJSON(t, "testdata/after.json"))
+}
+```
+
+## Document Caching
+
+When the same fixtures are loaded in multiple subtests, caching avoids re-parsing:
+
+```go
+ti, _ := testine.New(pt, testine.WithDocumentCache())
+```
+
+## API
+
+* **`Seed(t, doc) *Snapshot`** – Seed the database and capture the initial state for later comparison
+* **`Assert(t, expectedDoc)`** – Capture a snapshot and compare against expected state
+* **`Snapshot.Assert(t)`** – Compare the current database state against a previously captured snapshot
+* **`Cleanup(t)`** – Register a test cleanup function
+* **`LoadJSON(t, path)`** – Load JSON from a file, glob pattern, or directory, optionally using caching