Implementation:Treeverse LakeFS Lakectl Test Utilities

Knowledge Sources	Treeverse_LakeFS
Domains	Testing, CLI, Go
Last Updated	2026-02-08 00:00 GMT

Overview

The lakectl_util.go file provides Go utilities for integration-testing the lakectl CLI tool, including golden file management, output sanitization, variable expansion, and command execution helpers.

Description

This 312-line Go source file in the esti package contains the utility layer for testing the lakeFS command-line interface (lakectl). It implements a golden file testing pattern where expected CLI output is stored in .golden files and compared against sanitized actual output.

Key capabilities:

1. Output Sanitization: The file defines a comprehensive set of regular expressions to normalize non-deterministic values in CLI output:

• reTimestamp - Matches timestamp: <digits>
• reTime - Matches datetime strings like 2024-01-15 10:30:00 +0000 UTC
• reCommitID - Matches 64-character hex commit IDs
• reShortCommitID - Matches 16-character hex short commit IDs
• reChecksum - Matches 32-character hex checksums or 0x prefixed values
• reEndpoint - Matches lakeFS API endpoint URLs
• rePhysicalAddress - Matches physical storage object keys
• rePreSignURL - Matches pre-signed URLs with query parameters
• reSecretAccessKey - Matches secret access key values
• reAccessKeyID - Matches AWS-style access key IDs starting with AKIA

2. Variable Management:

• expandVariables - Replaces ${VAR_NAME} placeholders in strings with values from a map
• embedVariables - Reverse of expand; replaces known values with variable placeholders, processing longest values first to avoid partial replacements

3. Golden File Testing:

• RunCmdAndVerifySuccessWithFile - Runs a command and compares output against a golden file
• RunCmdAndVerifyFailureWithFile - Same as above but expects command failure
• updateGoldenFile - Runs a command and writes sanitized output to a golden file (activated via -update flag)

4. Command Execution and Verification:

• Lakectl - Returns the lakectl command string with credentials from Viper config
• LakectlWithParams - Returns lakectl command with explicit credentials
• LakectlWithPosixPerms - Returns lakectl command with POSIX permissions enabled
• RunCmdAndVerifySuccess - Runs a command and asserts output matches expected string
• RunCmdAndVerifyFailure - Runs a command and asserts failure with expected output
• RunCmdAndVerifyContainsText - Runs a command and asserts output contains expected substring
• RunCmdAndVerifyFailureContainsText - Same as above but expects command failure
• GetCommitter - Retrieves the current user's committer identity
• GetAuthor - Retrieves the current user's author ID and email

Usage

Use these utilities in lakectl integration tests. Set credentials and endpoint via Viper configuration. Use the RunCmdAndVerify* family of functions to execute lakectl commands and compare output against golden files or expected strings. Run tests with -update flag to regenerate golden files after intentional output changes.

Code Reference

Source Location

• Repository: Treeverse_LakeFS
• File: esti/lakectl_util.go
• Lines: 1-312

Signature

func Lakectl() string
func LakectlWithParams(accessKeyID, secretAccessKey, endPointURL string) string
func LakectlWithParamsWithPosixPerms(accessKeyID, secretAccessKey, endPointURL string, withPosixPerms bool) string
func LakectlWithPosixPerms() string

func RunCmdAndVerifySuccessWithFile(t *testing.T, cmd string, isTerminal bool, goldenFile string, vars map[string]string)
func RunCmdAndVerifyFailureWithFile(t *testing.T, cmd string, isTerminal bool, goldenFile string, vars map[string]string)
func RunCmdAndVerifySuccess(t *testing.T, cmd string, isTerminal bool, expected string, vars map[string]string)
func RunCmdAndVerifyFailure(t *testing.T, cmd string, isTerminal bool, expected string, vars map[string]string)
func RunCmdAndVerifyContainsText(t *testing.T, cmd string, isTerminal bool, expectedRaw string, vars map[string]string)
func RunCmdAndVerifyFailureContainsText(t *testing.T, cmd string, isTerminal bool, expectedRaw string, vars map[string]string)

func GetCommitter(t testing.TB) string
func GetAuthor(t testing.TB) (string, string)

Import

import (
	// This file is part of package esti; used internally by test files in the same package.
	// No external import path - co-located in esti/ directory.
)

I/O Contract

Inputs

Name	Type	Required	Description
t	*testing.T	Yes	Go test context for assertions, logging, and failure reporting
cmd	string	Yes	Shell command string to execute (typically a lakectl invocation)
isTerminal	bool	Yes	Whether to simulate terminal mode (sets LAKECTL_INTERACTIVE env var)
goldenFile	string	Conditional	Base name of the golden file (without path prefix or .golden suffix); required for file-based verification
expected	string	Conditional	Expected output string; required for string-based verification
vars	map[string]string	Yes	Variable name-to-value mapping for expansion and embedding (e.g., REPO, BRANCH, STORAGE, LAKEFS_ENDPOINT)

Outputs

Name	Type	Description
(assertions)	test failures	Functions use require.Equal/require.Contains to fail the test on mismatch
committer	string	User ID or email of the current authenticated user (from GetCommitter)
author, email	string, string	User ID and email (from GetAuthor)

Usage Examples

func TestLakectlBranchCreate(t *testing.T) {
	vars := map[string]string{
		"REPO":            repoName,
		"BRANCH":          branchName,
		"STORAGE":         storageNamespace,
		"LAKEFS_ENDPOINT": endpointURL + "/api/v1/",
	}

	// Run lakectl and compare to golden file
	RunCmdAndVerifySuccessWithFile(t,
		Lakectl()+" branch create lakefs://"+repoName+"/"+branchName+" -s lakefs://"+repoName+"/main",
		false,
		"lakectl_branch_create",
		vars,
	)

	// Run lakectl and check output contains text
	RunCmdAndVerifyContainsText(t,
		Lakectl()+" branch list lakefs://"+repoName,
		false,
		branchName,
		vars,
	)
}

Related Pages

• Principle:Treeverse_LakeFS_Integration_Test_Utilities