testeranto 0.200.0 → 0.202.0

package/example/vendor/github.com/adamwong246/testeranto/src/golingvu/README.md

@@ -0,0 +1,187 @@
+# Golingvu - Testeranto Implementation for Go
+
+## Understanding the Build Process
+
+The build process in Testeranto is inspired by esbuild's approach to bundling and metafile generation, adapted for multiple programming languages including Go, Python, and JavaScript variants.
+
+### Core Concepts
+
+#### 1. Metafile Generation
+Each language implementation generates a `core.json` metafile that tracks:
+- **Inputs**: Source files with their dependencies (imports) and metadata
+- **Outputs**: Generated/bundled files with their relationships to inputs
+- **Signatures**: Unique identifiers to track changes and trigger rebuilds
+
+#### 2. File Watching
+Two separate watchers work in tandem:
+1. **Source Watcher**: Monitors source files for changes and triggers metafile regeneration
+2. **Bundle Watcher**: Monitors generated files and schedules test execution when signatures change
+
+#### 3. Signature-based Change Detection
+- Each output file contains a unique signature in a comment
+- When source files change, new signatures are generated
+- Bundle watcher detects signature changes to trigger test execution
+
+### How esbuild's Approach is Adapted
+
+#### Original esbuild Flow:
+1. Parse entry points and resolve imports
+2. Bundle dependencies into output files
+3. Generate metafile with input/output relationships
+4. Watch for file changes and rebuild
+
+#### Testeranto Adaptation:
+1. **For each language**: Parse entry points and track dependencies
+2. **Instead of bundling**: Generate wrapper files that import/run the original tests
+3. **Generate metafile**: Track relationships between source files and generated wrappers
+4. **Watch system**: Dual watchers for source changes and bundle updates
+
+### Implementation Pattern for New Languages
+
+To add support for a new language (e.g., Rust, Java, C#), follow this pattern:
+
+#### 1. Metafile Generator (`src/utils/[language]Metafile.ts`)
+```typescript
+export async function generate[Language]Metafile(
+  testName: string,
+  entryPoints: string[]
+): Promise<[Language]Metafile> {
+  // Parse entry point files to find imports/dependencies
+  // Generate unique signature
+  // Return metafile structure with inputs and outputs
+}
+
+export function write[Language]Metafile(
+  testName: string,
+  metafile: [Language]Metafile
+): void {
+  // Write metafile to disk
+  // Generate output wrapper files with signatures
+}
+```
+
+#### 2. File Watcher (`src/utils/[language]Watcher.ts`)
+```typescript
+export class [Language]Watcher {
+  async start() {
+    // Set up source file watcher
+    // Set up bundle file watcher
+    // Handle file change events
+  }
+  
+  private async regenerateMetafile() {
+    // Regenerate metafile and output files
+  }
+}
+```
+
+#### 3. Language-specific Types (`src/[language]/types.[ext]`)
+Define interfaces for:
+- Test adapters
+- Resource configurations
+- Base test components (Given, When, Then)
+
+#### 4. Process Manager (`src/[language]/PM/[language].go`)
+Implement process communication for:
+- Starting/stopping tests
+- IPC communication
+- Resource management
+
+### Key Implementation Details
+
+#### Signature Handling
+- Use timestamp-based or content-hash signatures
+- Embed signatures in comments to avoid breaking code
+- Ensure consistent output filenames for reliable watching
+
+#### File Watching Strategy
+- Use `chokidar` for Node.js-based watching
+- Implement polling for reliability across filesystems
+- Handle edge cases: file deletions, renames, permission changes
+
+#### Metafile Structure
+```json
+{
+  "errors": [],
+  "warnings": [],
+  "metafile": {
+    "inputs": {
+      "path/to/file.ext": {
+        "bytes": 1024,
+        "imports": ["dependency1", "dependency2"]
+      }
+    },
+    "outputs": {
+      "output/path/file.ext": {
+        "imports": [],
+        "exports": [],
+        "entryPoint": "original/file.ext",
+        "inputs": {
+          "original/file.ext": {
+            "bytesInOutput": 1024
+          }
+        },
+        "bytes": 1024,
+        "signature": "unique_id"
+      }
+    }
+  }
+}
+```
+
+### Current Language Implementations
+
+#### Go (Golingvu)
+- **Entry points**: `.go` files with test functions
+- **Output**: Wrapper files that run `go test`
+- **Signature**: Timestamp in comments
+
+#### Python (Pitono)
+- **Entry points**: `.py` files with test cases
+- **Output**: Python modules with test runners
+- **Signature**: Content hash or timestamp
+
+#### JavaScript/TypeScript
+- **Entry points**: `.js`/`.ts` files
+- **Output**: Bundled JavaScript with esbuild
+- **Signature**: Integrated into build process
+
+### Common Challenges and Solutions
+
+1. **File Change Detection**
+   - Use polling with appropriate intervals
+   - Handle filesystem event limitations
+   - Implement manual fallback checks
+
+2. **Dependency Resolution**
+   - Parse language-specific import syntax
+   - Handle relative vs absolute imports
+   - Account for language-specific module systems
+
+3. **Cross-platform Compatibility**
+   - Normalize file paths
+   - Handle different line endings
+   - Account for filesystem case sensitivity
+
+4. **Performance**
+   - Debounce file change events
+   - Cache parsing results where possible
+   - Use efficient data structures for dependency tracking
+
+### Testing the Implementation
+
+For each new language, verify:
+1. Source file changes trigger metafile regeneration
+2. Bundle file changes trigger test execution
+3. Signatures are properly updated and detected
+4. All file paths are handled consistently
+5. Error cases are properly handled (missing files, parse errors)
+
+### Future Considerations
+
+- **Incremental builds**: Only rebuild changed portions
+- **Dependency caching**: Store parsed dependencies to avoid re-parsing
+- **Cross-language dependencies**: Handle cases where tests in one language depend on another
+- **Remote execution**: Support running tests in containers or remote environments
+
+This pattern allows Testeranto to maintain a consistent architecture while supporting multiple programming languages, each with their own unique characteristics and requirements.

package/example/vendor/github.com/adamwong246/testeranto/src/golingvu/base_given.go

@@ -0,0 +1,163 @@
+package golingvu
+
+import "fmt"
+
+// BaseGiven represents a base Given condition
+type BaseGiven struct {
+	Name           string
+	Features       []string
+	Whens          []*BaseWhen
+	Thens          []*BaseThen
+	Error          error
+	Fail           interface{}
+	Store          interface{}
+	RecommendedFsPath string
+	GivenCB        interface{}
+	InitialValues  interface{}
+	Key            string
+	Failed         bool
+	Artifacts      []string
+	GivenThatFunc  func(subject, testResource, artifactory, initializer, initialValues, pm interface{}) (interface{}, error)
+	AfterEachFunc  func(store interface{}, key string, artifactory, pm interface{}) (interface{}, error)
+	UberCatcherFunc func(func())
+}
+
+// AddArtifact adds an artifact path
+func (bg *BaseGiven) AddArtifact(path string) {
+	// Normalize path separators
+	// For simplicity, we'll assume paths are already normalized
+	bg.Artifacts = append(bg.Artifacts, path)
+}
+
+// NewBaseGiven creates a new BaseGiven instance
+func NewBaseGiven(name string, features []string, whens []*BaseWhen, thens []*BaseThen, givenCB, initialValues interface{}) *BaseGiven {
+	return &BaseGiven{
+		Name:          name,
+		Features:      features,
+		Whens:         whens,
+		Thens:         thens,
+		GivenCB:       givenCB,
+		InitialValues: initialValues,
+		Artifacts:     make([]string, 0),
+	}
+}
+
+// BeforeAll is called before all tests
+func (bg *BaseGiven) BeforeAll(store interface{}) interface{} {
+	return store
+}
+
+// ToObj converts the instance to a map for serialization
+func (bg *BaseGiven) ToObj() map[string]interface{} {
+	whenObjs := make([]map[string]interface{}, len(bg.Whens))
+	for i, w := range bg.Whens {
+		whenObjs[i] = w.ToObj()
+	}
+	
+	thenObjs := make([]map[string]interface{}, len(bg.Thens))
+	for i, t := range bg.Thens {
+		thenObjs[i] = t.ToObj()
+	}
+	
+	return map[string]interface{}{
+		"key":      bg.Key,
+		"name":     bg.Name,
+		"whens":    whenObjs,
+		"thens":    thenObjs,
+		"error":    bg.Error,
+		"failed":   bg.Failed,
+		"features": bg.Features,
+		"artifacts": bg.Artifacts,
+	}
+}
+
+// GivenThat is an abstract method to be implemented
+func (bg *BaseGiven) GivenThat(subject, testResourceConfiguration, artifactory, givenCB, initialValues, pm interface{}) (interface{}, error) {
+	// To be implemented by concrete types
+	return nil, nil
+}
+
+// AfterEach is called after each test
+func (bg *BaseGiven) AfterEach(store interface{}, key string, artifactory, pm interface{}) (interface{}, error) {
+	return store, nil
+}
+
+// UberCatcher handles errors
+func (bg *BaseGiven) UberCatcher(e error) {
+	bg.Error = e
+}
+
+// Give executes the given condition
+func (bg *BaseGiven) Give(
+	subject interface{},
+	key string,
+	testResourceConfiguration ITTestResourceConfiguration,
+	tester func(interface{}) bool,
+	artifactory func(string, interface{}),
+	tLog func(...string),
+	pm interface{},
+	suiteNdx int,
+) (interface{}, error) {
+	bg.Key = key
+	tLog("\n " + bg.Key)
+	tLog("\n Given: " + bg.Name)
+
+	// Setup
+	store, err := bg.GivenThat(
+		subject,
+		testResourceConfiguration,
+		artifactory,
+		bg.GivenCB,
+		bg.InitialValues,
+		pm,
+	)
+	if err != nil {
+		bg.Failed = true
+		bg.Error = err
+		return nil, err
+	}
+	bg.Store = store
+
+	// Process Whens
+	for whenNdx, when := range bg.Whens {
+		_, err := when.Test(
+			bg.Store,
+			testResourceConfiguration,
+			tLog,
+			pm,
+			fmt.Sprintf("suite-%d/given-%s/when/%d", suiteNdx, key, whenNdx),
+		)
+		if err != nil {
+			bg.Failed = true
+			bg.Error = err
+			return nil, err
+		}
+	}
+
+	// Process Thens
+	for thenNdx, then := range bg.Thens {
+		result, err := then.Test(
+			bg.Store,
+			testResourceConfiguration,
+			tLog,
+			pm,
+			fmt.Sprintf("suite-%d/given-%s/then-%d", suiteNdx, key, thenNdx),
+		)
+		if err != nil {
+			bg.Failed = true
+			bg.Error = err
+			return nil, err
+		}
+		tester(result)
+	}
+
+	// Cleanup
+	_, err = bg.AfterEach(bg.Store, bg.Key, artifactory, pm)
+	if err != nil {
+		bg.Failed = true
+		bg.Error = err
+		return nil, err
+	}
+
+	return bg.Store, nil
+}

package/example/vendor/github.com/adamwong246/testeranto/src/golingvu/base_suite.go

@@ -0,0 +1,85 @@
+package golingvu
+
+// BaseSuite represents a test suite
+type BaseSuite struct {
+	Name           string
+	Givens         map[string]*BaseGiven
+	AfterAllFunc   func(store interface{}, artifactory func(string, interface{}), pm interface{}) interface{}
+	AssertThatFunc func(t interface{}) bool
+	SetupFunc      func(s interface{}, artifactory func(string, interface{}), tr ITTestResourceConfiguration, pm interface{}) interface{}
+	Store          interface{}
+	TestResourceConfiguration ITTestResourceConfiguration
+	Index          int
+	Failed         bool
+	Fails          int
+	Artifacts      []string
+}
+
+// Run executes the test suite
+func (bs *BaseSuite) Run(input interface{}, testResourceConfiguration ITTestResourceConfiguration, artifactory func(string, interface{}), tLog func(...string), pm interface{}) (*BaseSuite, error) {
+	bs.TestResourceConfiguration = testResourceConfiguration
+	
+	// Setup
+	subject := bs.SetupFunc(input, artifactory, testResourceConfiguration, pm)
+	
+	// Run each given
+	for gKey, g := range bs.Givens {
+		_, err := g.Give(
+			subject,
+			gKey,
+			testResourceConfiguration,
+			bs.AssertThatFunc,
+			artifactory,
+			tLog,
+			pm,
+			bs.Index,
+		)
+		if err != nil {
+			bs.Failed = true
+			bs.Fails++
+			return bs, err
+		}
+	}
+	
+	// After all
+	bs.AfterAllFunc(bs.Store, artifactory, pm)
+	
+	return bs, nil
+}
+
+// ToObj converts the suite to a serializable object
+func (bs *BaseSuite) ToObj() map[string]interface{} {
+	givens := make([]map[string]interface{}, 0)
+	for _, given := range bs.Givens {
+		givens = append(givens, given.ToObj())
+	}
+	
+	return map[string]interface{}{
+		"name":    bs.Name,
+		"givens":  givens,
+		"fails":   bs.Fails,
+		"failed":  bs.Failed,
+		"features": bs.Features(),
+	}
+}
+
+// Features returns the features covered by this suite
+func (bs *BaseSuite) Features() []string {
+	features := make([]string, 0)
+	seen := make(map[string]bool)
+	
+	for _, given := range bs.Givens {
+		for _, feature := range given.Features {
+			if !seen[feature] {
+				features = append(features, feature)
+				seen[feature] = true
+			}
+		}
+	}
+	return features
+}
+
+// AddArtifact adds an artifact to the suite
+func (bs *BaseSuite) AddArtifact(path string) {
+	bs.Artifacts = append(bs.Artifacts, path)
+}

package/example/vendor/github.com/adamwong246/testeranto/src/golingvu/base_then.go

@@ -0,0 +1,21 @@
+package golingvu
+
+// BaseThen represents a Then condition
+type BaseThen struct {
+	Name        string
+	ThenCB      interface{}
+	ButThenFunc func(store, thenCB, testResource, pm interface{}) (interface{}, error)
+}
+
+// Test executes the Then condition
+func (bt *BaseThen) Test(store interface{}, testResourceConfiguration ITTestResourceConfiguration, tLog func(...string), pm interface{}, path string) (interface{}, error) {
+	// Implementation would go here
+	return nil, nil
+}
+
+// ToObj converts the Then condition to a serializable object
+func (bt *BaseThen) ToObj() map[string]interface{} {
+	return map[string]interface{}{
+		"name": bt.Name,
+	}
+}

package/example/vendor/github.com/adamwong246/testeranto/src/golingvu/base_when.go

@@ -0,0 +1,21 @@
+package golingvu
+
+// BaseWhen represents a When condition
+type BaseWhen struct {
+	Name        string
+	WhenCB      interface{}
+	AndWhenFunc func(store, whenCB, testResource, pm interface{}) (interface{}, error)
+}
+
+// Test executes the When condition
+func (bw *BaseWhen) Test(store interface{}, testResourceConfiguration ITTestResourceConfiguration, tLog func(...string), pm interface{}, path string) (interface{}, error) {
+	// Implementation would go here
+	return nil, nil
+}
+
+// ToObj converts the When condition to a serializable object
+func (bw *BaseWhen) ToObj() map[string]interface{} {
+	return map[string]interface{}{
+		"name": bw.Name,
+	}
+}