Getting Started with testmark v2🔗

Installation🔗

go get github.com/warpfork/go-testmark/v2@latest

For local testing with unreleased changes, add this to your go.mod:

require github.com/warpfork/go-testmark/v2 v0.0.0

replace github.com/warpfork/go-testmark/v2 => /path/to/local/go-testmark/v2

Basic Usage🔗

1. Core Functionality🔗

package main

import (
    "fmt"
    testmark "github.com/warpfork/go-testmark/v2"
)

func main() {
    // Parse automatically builds directory index
    doc := testmark.MustReadFile("example.md")
    
    // Clean API with type-safe generics
    hunk := testmark.NewHunk("config", "json", `{"host": "localhost"}`)
    
    // Immutable operations
    updated := doc.Patch(hunk)
    
    // Safe iteration
    iter := updated.Hunks()
    for hunk, ok := iter.Next(); ok; hunk, ok = iter.Next() {
        fmt.Printf("%s: %s\n", hunk.Name(), hunk.String())
    }
}

2. Command Execution🔗

package mytest

import (
    "testing"
    testmark "github.com/warpfork/go-testmark/v2"
    "github.com/warpfork/go-testmark/v2/testexec"
)

func TestCommands(t *testing.T) {
    doc := testmark.MustReadFile("tests.md")
    
    // Test any system command
    testexec.Test(t, doc.Root().Child("echo-test"))
    
    // Test Go programs with smart package resolution
    testexec.TestGo(t, doc.Root().Child("go-test"))
}

3. Experimental Documentation Testing🔗

package doctest

import (
    "os"
    "testing"
    "github.com/warpfork/go-testmark/v2/doctest"
)

func TestDocumentation(t *testing.T) {
    // Test Go code snippets in markdown files
    tester := doctest.New()
    tester.TestReadme(t, os.DirFS("."))
}

Key Improvements from v1🔗

✅ Eliminated Boilerplate🔗

// v1: Required manual steps
doc, _ := testmark.ReadFile("test.md")
doc.BuildDirIndex() // Manual!

// v2: Automatic
doc := testmark.MustReadFile("test.md") // Auto-indexed

✅ Type Safety🔗

// v1: Multiple functions, easy to get wrong
testmark.Hunk{Name: "test", Body: []byte("content")}

// v2: Generic, type-safe
testmark.NewHunk("test", "", "content")        // string
testmark.NewHunk("test", "", []byte{1,2,3})     // []byte
testmark.NewHunkFromReader("test", "", reader)  // io.Reader

✅ Immutable Operations🔗

// v2: Original never changes
original := testmark.MustReadFile("data.md")
modified := original.Patch(newHunk)
// 'original' is unchanged, 'modified' is new

✅ Modern Iterators🔗

// v2: Go-idiomatic (value, bool) pattern
iter := doc.Hunks()
for hunk, ok := iter.Next(); ok; hunk, ok = iter.Next() {
    fmt.Printf("Found: %s\n", hunk.Name())
}

✅ Clean Package Organization🔗

• Core functionality: github.com/warpfork/go-testmark/v2
• Command execution: github.com/warpfork/go-testmark/v2/testexec
• Documentation testing: github.com/warpfork/go-testmark/v2/doctest (experimental)

Migration from v1🔗

The core concepts remain the same, but the API is much cleaner:

v1 Pattern	v2 Replacement
doc.BuildDirIndex()	automatic
doc.DataHunks	doc.Hunks() iterator
doc.HunksByName[name]	doc.HunkByName(name)
doc.DirEnt.Children[name]	doc.Root().Child(name)
&testmark.PatchAccumulator{}	Built-in patching
Direct field access	Private fields + accessors
Mutable operations	Immutable (returns new docs)

Examples🔗

See the /examples directory for complete working examples of:

• Basic document manipulation
• Command execution testing
• Go program testing
• Documentation testing

The v2 API makes the "right thing" easy and the "wrong thing" impossible through thoughtful design! 🚀