Testmark v2 Enhanced Features🔗

Smart Go Execution🔗

Testmark v2 includes intelligent Go package resolution and convenient testing functions.

Basic Go Testing🔗

// Test the current package
func TestCurrentPackage(t *testing.T) {
    testmark.TestGoPackage(t, ".")
}

// Test a relative package
func TestSubPackage(t *testing.T) {
    testmark.TestGoPackage(t, "./subpkg")
}

// Test a Go file directly
func TestGoFile(t *testing.T) {
    testmark.TestGoFile(t, "main.go", "arg1", "arg2")
}

// Test Go code from a string
func TestGoCode(t *testing.T) {
    code := `package main
    import "fmt"
    func main() { fmt.Println("Hello, World!") }`
    testmark.TestGoScript(t, code)
}

Advanced Go Testing with Testmark Documents🔗

func TestGoWithTestmark(t *testing.T) {
    doc := testmark.MustParseString(`# Go Test

[testmark]:# (hello-world/sequence)
` + "```\n./myprogram\necho done\n```" + `

[testmark]:# (hello-world/output)
` + "```\nHello from my program\ndone\n```" + `

[testmark]:# (hello-world/fs/main.go)
` + "```go\npackage main\nimport \"fmt\"\nfunc main() { fmt.Println(\"Hello from my program\") }\n```" + `
`)

    entry := doc.Root().Child("hello-world")
    testmark.TestGo(t, entry) // Uses smart Go execution
}

Package Reference Resolution🔗

The smart Go executor understands various package reference formats:

• "." - Current package
• "./subpkg" - Relative package
• "../other" - Parent directory package
• "mypkg" - Package in current module
• "github.com/user/repo" - Full module path
• "main.go" - Go files (automatically uses go run)

Testable Documentation🔗

Testmark v2 can extract and test Go code snippets from your documentation!

Basic Documentation Testing🔗

func TestDocumentation(t *testing.T) {
    // Test all README files
    testmark.TestReadmeExamples(t, os.DirFS("."))
    
    // Test all markdown files
    testmark.TestAllDocExamples(t, os.DirFS("."))
}

Custom Documentation Testing🔗

func TestCustomDocs(t *testing.T) {
    doctest := testmark.DefaultDocTest()
    
    // Customize the package template for code snippets
    doctest.PackageTemplate = `package main

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

func main() {
%s
}`

    // Add custom skip patterns
    doctest.SkipPatterns = append(doctest.SkipPatterns, 
        regexp.MustCompile(`// EXAMPLE ONLY`),
    )
    
    // Test specific documentation files
    doctest.TestDocumentation(t, os.DirFS("."), "docs/*.md", "examples/*.md")
}

How Documentation Testing Works🔗

1. Extracts Go code blocks from markdown files
2. Identifies Go code by language hints (go, golang) or heuristics
3. Wraps incomplete snippets in a main function template
4. Validates syntax using Go's parser
5. Executes code using the smart Go executor
6. Reports failures as test failures with source location

Example: Testing This README🔗

You can make the code examples in this very README testable:

func TestThisReadme(t *testing.T) {
    // This will test all the Go code blocks above!
    testmark.TestReadmeExamples(t, os.DirFS("."))
}

Integration Examples🔗

Complete Test Suite🔗

// Test suite that combines testmark documents and documentation examples
func TestCompleteSuite(t *testing.T) {
    // Test regular testmark documents
    suite := testmark.NewSuite(fsx.DirFS("."))
    suite.MustAddExec("testdata/*.md", "*")
    suite.MustAddGoExec("go-tests/*.md", "*", "")
    suite.Run(t)
    
    // Test documentation examples
    testmark.TestAllDocExamples(t, os.DirFS("."))
}

CI/CD Integration🔗

// This ensures both your tests and documentation stay up-to-date
func TestEverything(t *testing.T) {
    t.Run("testmark-suite", func(t *testing.T) {
        suite := testmark.NewSuite(fsx.DirFS("."))
        suite.MustAddGoExec("*.md", "test-*", ".")
        suite.Run(t)
    })
    
    t.Run("documentation", func(t *testing.T) {
        testmark.TestAllDocExamples(t, os.DirFS("."))
    })
}

Key Benefits🔗

🚀 Simplified Go Testing🔗

• No need to specify full module paths in tests
• Intelligent package resolution (".", "./pkg", etc.)
• Built-in support for Go files and packages
• Zero configuration for common cases

📚 Living Documentation🔗

• Code examples in docs are automatically tested
• Documentation stays in sync with code
• Examples are guaranteed to work
• CI catches broken documentation

🔧 Developer Experience🔗

• Less boilerplate in test setup
• Familiar patterns (testmark.TestGoPackage(t, "."))
• Comprehensive error reporting with source locations
• Flexible customization when needed

🎯 Quality Assurance🔗

• Documentation examples can't go stale
• Test coverage includes all published examples
• Consistent behavior across different environments
• Early detection of breaking changes in examples

These features make testmark v2 not just a test framework, but a complete solution for ensuring your code, tests, and documentation all stay in perfect sync! 🎉