# Testmark v2 Enhanced Features

## Smart Go Execution

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

### Basic Go Testing

```go
// 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

```go
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

```go
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

```go
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:

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

## Integration Examples

### Complete Test Suite

```go
// 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

```go
// 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! 🎉