tools

package
v1.3.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 14, 2025 License: MIT Imports: 47 Imported by: 0

README

Package tools provides common methods and utilities for Go(lang) based development tools that cover:

  • integration tests (primarily, ais/test/*),
  • benchmarks (under bench/),
  • aisloader.

This package and its sub-packages (listed below) should not be linked into production code. Unlike, say, cmn package (that also contains common functions) devtools is solely intended for usage with development tools.

Package devtools itself contains a spectrum of general-purpose sources and is further sub-divided into packages that group closely related functions:

Folder Intended for
archive Create, list, and read from archives
readers Provides io.Reader and related primitives based on: random source, file, scatter-gather list
tassert Testing asserts - CheckFatal, Errorf, Fatalf, and other convenient assertions
tetl Common functions used for (and by) ETL tests
tlog Uniform logging for integrations tests

Documentation

Overview

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved.

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2023, NVIDIA CORPORATION. All rights reserved.

Package tools provides common tools and utilities for all unit and integration tests

  • Copyright (c) 2018-2022, NVIDIA CORPORATION. All rights reserved.

Index

Constants

View Source 
const (
	WaitClusterStartup    = 20 * time.Second
	RebalanceStartTimeout = 10 * time.Second
	MaxCplaneTimeout      = 10 * time.Second

	CopyBucketTimeout     = 3 * time.Minute
	MultiProxyTestTimeout = 3 * time.Minute

	DsortFinishTimeout   = 6 * time.Minute
	RebalanceTimeout     = 2 * time.Minute
	EvictPrefetchTimeout = 2 * time.Minute
	BucketCleanupTimeout = time.Minute
)

times and timeouts

View Source 
const (
	// This value is holds the input of 'proxyURLFlag' from init_tests.go.
	// It is used in BaseAPIParams to determine if the cluster is running
	// on a
	// 	1. local instance (no docker) 	- works
	//	2. local docker instance		- works
	// 	3. AWS-deployed cluster 		- not tested (but runs mainly with Ansible)
	MockDaemonID = "MOCK"
)

Variables

View Source 
var (
	RemoteCluster struct {
		UUID  string
		Alias string
		URL   string
	}
	LoggedUserToken string
)
View Source 
var ErrTimedOutStabilize = errors.New("timed out waiting for the cluster to stabilize")

Functions

func AddMpath 

func AddMpath(t *testing.T, path string)

func AssertMountpathCount 

func AssertMountpathCount(t *testing.T, na, nd int)

func BaseAPIParams 

func BaseAPIParams(urls ...string) api.BaseParams

func BucketExists 

func BucketExists(tb testing.TB, proxyURL string, bck cmn.Bck) (bool, error)

func BucketsContain 

func BucketsContain(bcks cmn.Bcks, qbck cmn.QueryBcks) bool

func CheckErrIsNotFound 

func CheckErrIsNotFound(t *testing.T, err error)

func CheckObjIsPresent 

func CheckObjIsPresent(proxyURL string, bck cmn.Bck, objName string) bool

func CheckPathExists 

func CheckPathExists(t *testing.T, path string, dir bool)

func CheckPathNotExists 

func CheckPathNotExists(t *testing.T, path string)

func CheckSkip 

func CheckSkip(tb testing.TB, args *SkipTestArgs)

func CleanupNode 

func CleanupNode(t *testing.T, pid int)

CleanupNode kills the process.

func CleanupRemoteBucket 

func CleanupRemoteBucket(t *testing.T, proxyURL string, bck cmn.Bck, prefix string)

func ClearMaintenance 

func ClearMaintenance(bp api.BaseParams, tsi *meta.Snode)

func CreateBucket added in v1.3.19 

func CreateBucket(tb testing.TB, proxyURL string, bck cmn.Bck, props *cmn.BpropsToSet, cleanup bool)

func CreateFileFromReader 

func CreateFileFromReader(t *testing.T, fileName string, r io.Reader) string

func Del 

func Del(proxyURL string, bck cmn.Bck, object string, wg *sync.WaitGroup, errCh chan error, silent bool) error

func DeployNode 

func DeployNode(t *testing.T, node *meta.Snode, conf *cmn.Config, localConf *cmn.LocalConfig) int

func DestroyBucket 

func DestroyBucket(tb testing.TB, proxyURL string, bck cmn.Bck)

is usually called to cleanup (via tb.Cleanup)

func DisableRebalance added in v1.3.24 

func DisableRebalance(t *testing.T)

func EnableRebalance added in v1.3.24 

func EnableRebalance(t *testing.T)

func EnsureObjectsExist 

func EnsureObjectsExist(t *testing.T, params api.BaseParams, bck cmn.Bck, objectsNames ...string)

func EnsureOrigClusterState 

func EnsureOrigClusterState(t *testing.T)

EnsureOrigClusterState verifies the cluster has the same nodes after tests If a node is killed, it restores the node

func EvictObjects 

func EvictObjects(t *testing.T, proxyURL string, bck cmn.Bck, lst []string)

func EvictRemoteBucket 

func EvictRemoteBucket(tb testing.TB, proxyURL string, bck cmn.Bck)

func FilesEqual 

func FilesEqual(file1, file2 string) (bool, error)

func GenerateNonexistentBucketName 

func GenerateNonexistentBucketName(prefix string, bp api.BaseParams) (string, error)

func GenerateNotConflictingObjectName 

func GenerateNotConflictingObjectName(baseName, newNamePrefix string, bck cmn.Bck, smap *meta.Smap) string

Generates an object name that hashes to a different target than `baseName`.

func GetClusterConfig 

func GetClusterConfig(t *testing.T) (config *cmn.Config)

func GetClusterMap 

func GetClusterMap(tb testing.TB, url string) *meta.Smap

func GetClusterStats 

func GetClusterStats(t *testing.T, proxyURL string) stats.Cluster

func GetDaemonConfig 

func GetDaemonConfig(t *testing.T, node *meta.Snode) *cmn.Config

func GetICProxy 

func GetICProxy(t testing.TB, smap *meta.Smap, ignoreID string) *meta.Snode

Return the first proxy from smap that is IC member. The primary proxy has higher priority.

func GetNamedStatsVal 

func GetNamedStatsVal(ds *stats.Node, name string) int64

func GetObjectAtime 

func GetObjectAtime(t *testing.T, bp api.BaseParams, bck cmn.Bck, object, timeFormat string) (time.Time, string)

func GetPrimaryProxy 

func GetPrimaryProxy(proxyURL string) (*meta.Snode, error)

GetPrimaryProxy returns the primary proxy

func GetPrimaryURL 

func GetPrimaryURL() string

func GetProxyReadiness 

func GetProxyReadiness(proxyURL string) error

func GetTargetsMountpaths 

func GetTargetsMountpaths(t *testing.T, smap *meta.Smap, params api.BaseParams) map[*meta.Snode][]string

func InitCluster 

func InitCluster(proxyURL string, clusterType ClusterType) (err error)

InitCluster initializes the environment necessary for testing against an AIS cluster. NOTE: the function is also used for testing by NVIDIA/ais-k8s Operator

func InitLocalCluster 

func InitLocalCluster()

InitLocalCluster initializes AIS cluster that must be either:

  1. deployed locally using `make deploy` command and accessible @ localhost:8080, or
  2. deployed in local docker environment, or
  3. provided via `AIS_ENDPOINT` environment variable

In addition, try to query remote AIS cluster that may or may not be locally deployed as well.

func JoinCluster 

func JoinCluster(proxyURL string, node *meta.Snode) (string, error)

Add an alive node that is not in SMap to the cluster. Use to add a new node to the cluster or get back a node removed by `RemoveNodeUnsafe`

func ListObjectNames 

func ListObjectNames(proxyURL string, bck cmn.Bck, prefix string, objectCountLimit int64, cached bool) ([]string, error)

ListObjectNames returns a slice of object names of all objects that match the prefix in a bucket

func ModifyLOM added in v1.3.24 

func ModifyLOM(t *testing.T, fqn string, bck cmn.Bck, modify func(*testing.T, *core.LOM))

func NewClientWithProxy 

func NewClientWithProxy(proxyURL string) *http.Client

func PrepareDirTree 

func PrepareDirTree(tb testing.TB, desc DirTreeDesc) (string, []string)

func PrepareMountPaths 

func PrepareMountPaths(t *testing.T, cnt int) fs.MPI

func Put 

func Put(proxyURL string, bck cmn.Bck, objName string, reader readers.Reader, errCh chan error)

Put sends a PUT request to the given URL

func PutObjRR 

func PutObjRR(bp api.BaseParams, bck cmn.Bck, objName string, objSize int64, cksumType string) error

func PutObject 

func PutObject(t *testing.T, bck cmn.Bck, objName string, reader readers.Reader)

PutObject sends a PUT request to the given URL.

func PutObjectInRemoteBucketWithoutCachingLocally 

func PutObjectInRemoteBucketWithoutCachingLocally(t *testing.T, bck cmn.Bck, object string, objContent cos.ReadOpenCloser)

Put an object into a cloud bucket and evict it afterwards - can be used to test cold GET

func PutRR 

func PutRR(tb testing.TB, bp api.BaseParams, objSize int64, cksumType string,
	bck cmn.Bck, dir string, objCount int) []string

func PutRandObjs 

func PutRandObjs(args PutObjectsArgs) ([]string, int, error)

func RandomObjDir 

func RandomObjDir(dirLen, maxDepth int) (dir string)

func RandomProxyURL 

func RandomProxyURL(ts ...*testing.T) (url string)

func RemoveMpaths 

func RemoveMpaths(t *testing.T, mpaths fs.MPI)

func RemoveNodeUnsafe added in v1.3.18 

func RemoveNodeUnsafe(proxyURL, sid string) error

Internal API to remove a node from Smap: use it to unregister MOCK targets/proxies. Use `JoinCluster` to attach node back.

func RestoreNode 

func RestoreNode(cmd RestoreCmd, asPrimary bool, tag string) error

func RestoreTarget 

func RestoreTarget(t *testing.T, proxyURL string, target *meta.Snode) (rebID string, newSmap *meta.Smap)

Restore a node put into maintenance: in this case the node is in Smap and canceling maintenance gets the node back.

func RmTargetSkipRebWait 

func RmTargetSkipRebWait(t *testing.T, proxyURL string, smap *meta.Smap) (*meta.Smap, *meta.Snode)

func SetBackendBck 

func SetBackendBck(t *testing.T, bp api.BaseParams, srcBck, dstBck cmn.Bck)

func SetClusterConfig 

func SetClusterConfig(t *testing.T, nvs cos.StrKVs)

func SetClusterConfigUsingMsg 

func SetClusterConfigUsingMsg(t *testing.T, toUpdate *cmn.ConfigToSet)

func SetRemAisConfig added in v1.3.23 

func SetRemAisConfig(t *testing.T, nvs cos.StrKVs)

func SetXattrCksum 

func SetXattrCksum(fqn string, bck cmn.Bck, cksum *cos.Cksum) error

func ShortSkipf 

func ShortSkipf(tb testing.TB, a ...any)

func WaitForClusterState 

func WaitForClusterState(proxyURL, reason string, origVer int64, pcnt, tcnt int, ignoreIDs ...string) (*meta.Smap, error)

WaitForClusterState waits until a cluster reaches specified state, meaning: - smap has version larger than origVersion - number of active proxies is equal proxyCnt, unless proxyCnt == 0 - number of active targets is equal targetCnt, unless targetCnt == 0.

It returns the smap which satisfies those requirements. NOTE: Upon successful return from this function cluster state might have already changed.

func WaitForClusterStateActual 

func WaitForClusterStateActual(proxyURL, reason string, origVersion int64, proxyCnt, targetCnt int,
	syncIgnoreIDs ...string) (*meta.Smap, error)

WaitForClusterStateActual waits until a cluster reaches specified state, meaning: - smap has version larger than origVersion - number of proxies in Smap is equal proxyCnt, unless proxyCnt == 0 - number of targets in Smap is equal targetCnt, unless targetCnt == 0.

It returns the smap which satisfies those requirements.

func WaitForDsortToFinish added in v1.3.21 

func WaitForDsortToFinish(proxyURL, managerUUID string) (allAborted bool, err error)

WaitForDsortToFinish waits until all dSorts jobs finished without failure or all jobs abort.

func WaitForNewSmap 

func WaitForNewSmap(proxyURL string, prevVersion int64) (newSmap *meta.Smap, err error)

func WaitForObjectToBeDowloaded 

func WaitForObjectToBeDowloaded(bp api.BaseParams, bck cmn.Bck, objName string, timeout time.Duration) error

func WaitForPID added in v1.3.21 

func WaitForPID(pid int) error

func WaitForRebalAndResil 

func WaitForRebalAndResil(t testing.TB, bp api.BaseParams, timeouts ...time.Duration)

TODO -- FIXME: revise and rewrite

Waits for both resilver and rebalance to complete. If they were not started, this function treats them as completed and returns. If timeout set, if any of rebalances doesn't complete before timeout the function ends with fatal.

func WaitForRebalanceByID 

func WaitForRebalanceByID(t *testing.T, bp api.BaseParams, rebID string, timeouts ...time.Duration)

func WaitForResilvering 

func WaitForResilvering(t *testing.T, bp api.BaseParams, target *meta.Snode)

func WaitNodeAdded 

func WaitNodeAdded(bp api.BaseParams, nodeID string) (*meta.Smap, error)

func WaitNodePubAddrNotInUse added in v1.3.20 

func WaitNodePubAddrNotInUse(si *meta.Snode, timeout time.Duration) error

as the name implies

func WaitNodeReady 

func WaitNodeReady(url string, opts ...*WaitRetryOpts) (err error)

Types

type ClusterType 

type ClusterType string
const (
	ClusterTypeLocal  ClusterType = "local"
	ClusterTypeDocker ClusterType = "docker"
	ClusterTypeK8s    ClusterType = "k8s"
)

Cluster type used for test

type ContentTypeDesc 

type ContentTypeDesc struct {
	Type       string
	ContentCnt int
}

type DirTreeDesc 

type DirTreeDesc struct {
	InitDir  string // Directory where the tree is created (can be empty).
	Dirs     int    // Number of (initially empty) directories at each depth (we recurse into single directory at each depth).
	Files    int    // Number of files at each depth.
	FileSize int64  // Size of each file.
	Depth    int    // Depth of tree/nesting.
	Empty    bool   // Determines if there is a file somewhere in the directories.
}

type E2EFramework 

type E2EFramework struct {
	Dir  string
	Vars map[string]string // Custom variables passed to input and output files.
}

func (*E2EFramework) RunE2ETest 

func (f *E2EFramework) RunE2ETest(fileName string)

type ObjectsDesc 

type ObjectsDesc struct {
	CTs           []ContentTypeDesc // Content types which are interesting for the test.
	MountpathsCnt int               // Number of mountpaths to be created.
	ObjectSize    int64
}

type ObjectsOut 

type ObjectsOut struct {
	Dir             string
	Bck             cmn.Bck
	FQNs            map[string][]string // ContentType => FQN
	MpathObjectsCnt map[string]int      // mpath -> # objects on the mpath
}

func PrepareObjects 

func PrepareObjects(t *testing.T, desc ObjectsDesc) *ObjectsOut

type PutObjectsArgs 

type PutObjectsArgs struct {
	ProxyURL  string
	Bck       cmn.Bck
	ObjPath   string
	CksumType string
	ObjSize   uint64
	ObjCnt    int
	ObjNameLn int
	WorkerCnt int
	FixedSize bool
	Ordered   bool // true - object names make sequence, false - names are random
	IgnoreErr bool
}

type RestoreCmd 

type RestoreCmd struct {
	Node *meta.Snode
	Cmd  string
	Args []string
	PID  int
}

command used to restore a node

func GetRestoreCmd 

func GetRestoreCmd(si *meta.Snode) RestoreCmd

func KillNode 

func KillNode(node *meta.Snode) (cmd RestoreCmd, err error)

func ShutdownNode 

func ShutdownNode(_ *testing.T, bp api.BaseParams, node *meta.Snode) (pid int, cmd RestoreCmd, rebID string, err error)

type SkipTestArgs 

type SkipTestArgs struct {
	Bck                   cmn.Bck
	RequiredDeployment    ClusterType
	MinTargets            int
	MinProxies            int
	MinMountpaths         int
	RequiresRemoteCluster bool
	RequiresAuth          bool
	RequiresTLS           bool
	Long                  bool
	RemoteBck             bool
	CloudBck              bool
	RequiredCloudProvider string
	K8s                   bool
	Local                 bool
}

type WaitRetryOpts 

type WaitRetryOpts struct {
	MaxRetries int
	Interval   time.Duration
}

Source Files

View all Source files

Directories

Path Synopsis
Packager docker provides common utilities for managing containerized AIS deployments
 Packager docker provides common utilities for managing containerized AIS deployments
Package readers provides implementation for common reader types
 Package readers provides implementation for common reader types
Package archive provides common low-level utilities for testing archives
 Package archive provides common low-level utilities for testing archives
Package tassert provides common asserts for tests
 Package tassert provides common asserts for tests
Package tetl provides helpers for ETL.
 Package tetl provides helpers for ETL.
Package tlog provides common logf and logln primitives for dev tools
 Package tlog provides common logf and logln primitives for dev tools
Package trand provides random string for dev tools and tests
 Package trand provides random string for dev tools and tests

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.