README
¶
GoScript Compliance Tests
The compliance tests verify that Go code can be correctly transpiled to TypeScript and produce the same output as the original Go code.
Test Structure
Each compliance test is a directory under tests/tests/ containing:
Core Files:
*.go- Go source code to be transpiled*.gs.ts- Generated TypeScript files (auto-created, do not edit manually)expected.log- Expected output when running the code (auto-generated from Go if missing)actual.log- Actual output from TypeScript (created when tests fail)
Configuration Files (all optional):
packages- List of packages to compile (one per line, supports comments with #)skip-test- Skip this test entirelyexpect-fail- Test compilation but skip executionskip-typecheck- Skip TypeScript type checkingexpect-typecheck-fail- Expect TypeScript type checking to failno-all-deps- Disable automatic dependency compilation
Generated Files:
index.ts- Package index files (auto-generated)tsconfig.json- TypeScript configuration for type checking (auto-generated)
Test Lifecycle
When a compliance test runs, the following steps occur:
1. Preparation
- Creates a temporary
run/directory in the test folder - Sets up TypeScript configuration files
- Determines which packages need to be compiled
2. Compilation
- Compiles Go source files to TypeScript using the GoScript compiler
- Outputs to
run/output/@goscript/MODULE_PATH/tests/tests/TEST_NAME/ - Copies generated
.gs.tsandindex.tsfiles back to the test directory - Adds header comments to
.gs.tsfiles indicating they're auto-generated - Copies dependency packages to
tests/deps/for git tracking
3. Execution (unless expect-fail present)
- Generates a
runner.tsscript that imports and executes the main function - Runs the TypeScript code using
bun - Captures stdout output
4. Comparison (unless expect-fail present)
- Compares TypeScript output with
expected.log - If
expected.logdoesn't exist, generates it by runninggo run ./ - Creates
actual.logif outputs differ
5. Type Checking (unless skipped)
- Generates a
tsconfig.jsonfor type checking the generated files - Runs
tscto verify TypeScript types are correct - Uses path mapping to resolve
@goscript/*imports
Multi-Package Tests
Tests can contain multiple packages in subdirectories:
test_name/
├── main.go # Main package
├── subpkg/
│ └── helper.go # Subpackage
└── packages # Optional: explicit package list
The compiler auto-detects packages by scanning for .go files, or uses the packages file if present.
packages file format:
./
./subpkg
./another/package
# Lines starting with # are comments
Dependency Management
The test system automatically handles dependencies:
- Builtin packages - Handwritten TypeScript in
gs/directory - Test dependencies - Automatically compiled and cached in
tests/deps/ - Path mapping - TypeScript imports resolved via
@goscript/*paths
Dependencies are copied to tests/deps/ to ensure they're tracked in git and available for type checking.
Running Tests
All compliance tests
go test -v ./compiler
Specific test
go test -timeout 30s -run ^TestCompliance/test_name$ ./compiler
Documentation
¶
Index ¶
- func CompileGoToTypeScript(t *testing.T, parentModulePath, testDir, tempDir, outputDir string, ...)
- func PrepareTestRunDir(t *testing.T, testDir string) string
- func ReadExpectedLog(t *testing.T, testDir string) string
- func RunGoScriptTestDir(t *testing.T, workspaceDir, testDir string)
- func RunTypeScriptRunner(t *testing.T, workspaceDir, tempDir, tsRunner string) string
- func RunTypeScriptTypeCheck(t *testing.T, workspaceDir, testDir string, tsconfigPath string)
- func WriteGlobalTypeCheckConfig(t *testing.T, parentModulePath, workspaceDir string) string
- func WriteTypeCheckConfig(t *testing.T, parentModulePath, workspaceDir, testDir string) string
- func WriteTypeScriptRunner(t *testing.T, parentModulePath, testDir, tempDir string) string
- type TestCase
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompileGoToTypeScript ¶
func CompileGoToTypeScript(t *testing.T, parentModulePath, testDir, tempDir, outputDir string, le *logrus.Entry)
CompileGoToTypeScript compiles Go source files from a test directory into TypeScript. It uses the goscript compiler to perform the compilation.
Parameters:
- t: The testing.T instance for logging and assertions.
- parentModulePath: The Go module path of the parent project (e.g., "github.com/user/repo").
- testDir: The directory containing the Go source files for the test (can be relative or absolute).
- tempDir: The temporary directory where compilation artifacts (like the output directory) are managed. This is typically the "run" subdirectory created by PrepareTestRunDir (can be relative or absolute).
- outputDir: The directory within tempDir where the compiled TypeScript files will be placed, structured under "@goscript/PARENT_MODULE_PATH/tests/tests/TEST_NAME/...".
- le: A logrus.Entry for logging.
The function walks the testDir to find all .go files, determines their package structure, and then invokes the goscript compiler. After compilation, it copies the generated .gs.ts files and any index.ts files from the outputDir back into the original testDir, adding a header comment to the .gs.ts files. This allows the generated TypeScript to be reviewed and committed alongside the Go source.
func PrepareTestRunDir ¶
PrepareTestRunDir creates a temporary directory structure for running a single compliance test. It creates a "run" subdirectory within the provided testDir. This "run" directory will house the compiled TypeScript, runner scripts, and other temporary files. It ensures a clean state by removing the "run" directory if it already exists.
func ReadExpectedLog ¶
ReadExpectedLog reads the content of the "expected.log" file from the given testDir. This file contains the expected stdout output when the Go version of the test is run. It's used to compare against the output of the compiled TypeScript code.
func RunGoScriptTestDir ¶
RunGoScriptTestDir orchestrates the full lifecycle of a single compliance test located in a specific directory (testDir).
The process involves: 1. Determining the parent Go module path. 2. Checking for a "skip-test" file; if present, the test is skipped. 3. Preparing a test run directory within testDir. 4. Setting up a "tsconfig.json" and "package.json" in the "run" directory for executing the compiled TypeScript. 5. Compiling Go source files from testDir to TypeScript, placing them in "run/output/...".
- Generated .gs.ts and index.ts files are copied back to testDir. 6. Writing a "runner.ts" script in the "run" directory to execute the compiled test. 7. If an "expect-fail" file is not present in testDir: a. Running the "runner.ts" script using `bun`. b. Comparing its output against "expected.log" (generating it from `go run ./` if it doesn't exist).
- If outputs differ, "actual.log" is written to testDir. 8. If "skip-typecheck" or "expect-typecheck-fail" files are not present: a. Writing a "tsconfig.json" in testDir for type checking the generated .gs.ts files. b. Running `tsc` to perform the type check.
Parameters:
- t: The testing.T instance for logging and assertions.
- workspaceDir: The root directory of the goscript workspace (can be relative or absolute).
- testDir: The directory containing the Go source files and configuration for a single compliance test (can be relative or absolute).
func RunTypeScriptRunner ¶
RunTypeScriptRunner executes the generated "runner.ts" script using `bun run`. It captures and returns the standard output of the script.
Parameters:
- t: The testing.T instance for logging and assertions.
- workspaceDir: The root directory of the goscript workspace (unused but kept for API compatibility).
- tempDir: The directory where "runner.ts" and its `tsconfig.json` are located. The command is executed from this directory.
- tsRunner: The path to the "runner.ts" file, typically within tempDir.
The function requires `bun` to be installed on the system. It runs the script and returns its stdout. If the script execution fails, it calls t.Fatalf.
func RunTypeScriptTypeCheck ¶
RunTypeScriptTypeCheck executes the TypeScript compiler (`tsc`) to perform type checking on the generated TypeScript files in a test directory.
Parameters:
- t: The testing.T instance for logging and assertions.
- workspaceDir: The root directory of the goscript workspace. Used to find the `tsc` executable in `node_modules/.bin`.
- testDir: The directory of the specific compliance test, where the `tsconfig.json` (generated by WriteTypeCheckConfig) is located.
- tsconfigPath: The path to the `tsconfig.json` file to be used for type checking. This is typically `testDir/tsconfig.json`.
The function runs `tsc --project <tsconfigPath>` from the testDir. It sets up the PATH environment variable to include the local `node_modules/.bin`. If type checking fails, it calls t.Fatalf.
func WriteGlobalTypeCheckConfig ¶
WriteGlobalTypeCheckConfig generates a "tsconfig.json" file in "./tests/typecheck/" for type-checking all .gs.ts files across all compliance tests. It uses `git ls-files` to find all .gs.ts files and filters out any that are in test directories containing "expect-typecheck-fail", "skip-test", or "expect-fail" files.
Parameters:
- t: The testing.T instance for logging and assertions.
- parentModulePath: The Go module path of the parent project.
- workspaceDir: The root directory of the goscript workspace.
Returns the path to the generated "tsconfig.json" file.
func WriteTypeCheckConfig ¶
WriteTypeCheckConfig generates a "tsconfig.json" file in the testDir. This tsconfig.json is specifically configured for type-checking the .gs.ts files that were generated by CompileGoToTypeScript and copied back into the testDir.
Parameters:
- t: The testing.T instance for logging and assertions.
- parentModulePath: The Go module path of the parent project.
- workspaceDir: The root directory of the goscript workspace. Used to locate the root `tsconfig.json` and the `builtin.ts` file.
- testDir: The directory of the specific compliance test. The "tsconfig.json" will be written here, and paths within it will be relative to this directory.
The generated tsconfig.json extends the root tsconfig.json from the workspace. It includes all "*.gs.ts" and "index.ts" files found recursively within testDir. It sets up "paths" aliases for:
- The test's own generated package: "@goscript/PARENT_MODULE/tests/tests/TEST_NAME/*" -> "./*"
- The goscript builtin types: "@goscript/builtin" -> relative path to "workspaceDir/gs/builtin/index.ts"
Returns the path to the generated "tsconfig.json" file.
func WriteTypeScriptRunner ¶
WriteTypeScriptRunner generates a "runner.ts" file in the tempDir. This runner script imports the main function from the compiled TypeScript output of the test and executes it.
Parameters:
- t: The testing.T instance for logging and assertions.
- parentModulePath: The Go module path of the parent project.
- testDir: The directory containing the original Go source files for the test. This is used to determine the primary Go file and thus the entry point for the TypeScript runner.
- tempDir: The temporary directory (e.g., "testDir/run") where "runner.ts" will be written.
The function attempts to find a .go file (preferring one in the root of testDir) to determine the corresponding .gs.ts file that should contain the `main` function. It then constructs an import path for this .gs.ts file relative to the tempDir's structure (e.g., "./output/@goscript/PARENT_MODULE/tests/tests/TEST_NAME/main.gs.ts"). The content of "runner.ts" is based on runnerContentTemplate. Returns the path to the generated "runner.ts" file.
Types ¶
type TestCase ¶
type TestCase struct {
// Name is the name of the test case.
Name string
// GoSource is the Go source code for the test.
GoSource string
// ExpectedOutput is the expected output when the compiled TypeScript is run.
ExpectedOutput string
}
TestCase defines a single Go-to-TypeScript compliance test. This type is typically used when defining a suite of tests programmatically, though the current compliance test setup primarily relies on directory-based tests.
Source Files
Directories