sandbox

package
v0.4.4-rc2 Latest Latest
Warning

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

 Go to latest Published: Jan 5, 2024 License: MPL-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package sandbox provides an easy way to setup isolated terramate projects that can be used on testing, acting like sandboxes.

It helps with:

- git initialization/operations - Terraform module creation - Terramate stack creation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AssertTreeOption added in v0.4.3 

type AssertTreeOption func(o *assertTreeOptions)

AssertTreeOption is the common option type for AssertTree.

func WithStrictStackValidation added in v0.4.3 

func WithStrictStackValidation() AssertTreeOption

WithStrictStackValidation is an option for AssertTree to validate that the list of stacks given in the layout _exactly_ matches the list of stacks in the tree, i.e. it doesn't just check that the given stacks exist, but also that there are no other stacks beyond that.

type DirEntry 

type DirEntry struct {
	// contains filtered or unexported fields
}

DirEntry represents a directory and can be used to create files inside the directory.

func (DirEntry) Chmod 

func (de DirEntry) Chmod(relpath string, mode stdfs.FileMode)

Chmod does the same as test.Chmod for the given file/dir inside this DirEntry.

func (DirEntry) CreateConfig 

func (de DirEntry) CreateConfig(body string) FileEntry

CreateConfig will create a Terramate config file inside this dir entry with the given body using the default Terramate config filename.

It returns a file entry that can be used to further manipulate the created file, like replacing its contents. The file entry is optimized for always replacing the file contents, not streaming (using file as io.Writer).

If the file already exists its contents will be truncated, like os.Create behavior: https://pkg.go.dev/os#Create

func (DirEntry) CreateDir 

func (de DirEntry) CreateDir(relpath string) DirEntry

CreateDir creates a directory inside the dir entry directory. The relpath must be relative to the stack directory.

func (DirEntry) CreateFile 

func (de DirEntry) CreateFile(name, body string, args ...interface{}) FileEntry

CreateFile will create a file inside this dir entry with the given name and the given body. The body can be plain text or a format string identical to what is defined on Go fmt package.

It returns a file entry that can be used to further manipulate the created file, like replacing its contents. The file entry is optimized for always replacing the file contents, not streaming (using file as io.Writer).

If the file already exists its contents will be truncated, like os.Create behavior: https://pkg.go.dev/os#Create

func (DirEntry) DeleteConfig 

func (de DirEntry) DeleteConfig()

DeleteConfig deletes the default Terramate config file.

func (DirEntry) Git 

func (de DirEntry) Git() *Git

Git returns a Git wrapper for the dir.

func (DirEntry) ListGenFiles 

func (de DirEntry) ListGenFiles(root *config.Root) []string

ListGenFiles lists all files generated by Terramate for this dir entry.

func (DirEntry) Path 

func (de DirEntry) Path() string

Path returns the absolute path of the directory entry.

func (DirEntry) ReadFile 

func (de DirEntry) ReadFile(name string) []byte

ReadFile will read a file inside this dir entry with the given name. It will fail the test if the file doesn't exist, since it assumes an expectation on the file being there.

func (DirEntry) RelPath 

func (de DirEntry) RelPath() string

RelPath returns the relative path of the directory entry using the host path separator.

func (DirEntry) RemoveFile 

func (de DirEntry) RemoveFile(name string)

RemoveFile will delete a file inside this dir entry with the given name. It will succeeds if the file already doesn't exist.

type FileEntry 

type FileEntry struct {
	// contains filtered or unexported fields
}

FileEntry represents a file and can be used to manipulate the file contents. It is optimized for reading/writing all contents, not stream programming (io.Reader/io.Writer). It has limited usefulness but it is easier to work with for testing.

func (FileEntry) Chmod 

func (fe FileEntry) Chmod(mode os.FileMode)

Chmod changes the file mod, like os.Chmod.

func (FileEntry) HostPath 

func (fe FileEntry) HostPath() string

HostPath returns the absolute path of the file.

func (FileEntry) Path 

func (fe FileEntry) Path() string

Path returns the absolute project path of the file.

func (FileEntry) Write 

func (fe FileEntry) Write(body string, args ...interface{})

Write writes the given text body on the file, replacing its contents. The body can be plain text or a format string identical to what is defined on Go fmt package.

It behaves like os.WriteFile: https://pkg.go.dev/os#WriteFile

type Git 

type Git struct {
	// contains filtered or unexported fields
}

Git is a git wrapper that makes testing easy by handling errors automatically, failing the caller test.

func NewGit 

func NewGit(t testing.TB, repodir string) *Git

NewGit creates a new git wrapper using sandbox defaults.

func NewGitWithConfig 

func NewGitWithConfig(t testing.TB, cfg GitConfig) *Git

NewGitWithConfig creates a new git wrapper with the provided GitConfig.

func (Git) Add 

func (git Git) Add(files ...string)

Add will add files to the commit list

func (Git) AddSubmodule 

func (git Git) AddSubmodule(name string, url string)

AddSubmodule adds name as a submodule for the provided url.

func (*Git) BareRepoAbsPath 

func (git *Git) BareRepoAbsPath() string

BareRepoAbsPath returns the path for the bare remote repository of this repository.

func (Git) BaseDir 

func (git Git) BaseDir() string

BaseDir the repository base dir

func (Git) Checkout 

func (git Git) Checkout(rev string)

Checkout will checkout a pre-existing revision

func (Git) CheckoutNew 

func (git Git) CheckoutNew(rev string)

CheckoutNew will checkout a new revision (creating it on the process)

func (Git) Clone 

func (git Git) Clone(repoURL, dir string)

Clone will clone a repository into the given dir.

func (Git) Commit 

func (git Git) Commit(msg string, args ...string)

Commit will commit previously added files

func (Git) CommitAll 

func (git Git) CommitAll(msg string, ignoreErr ...bool)

CommitAll will add all changed files and commit all of them. It requires files to be committed otherwise it fails.

func (*Git) CurrentBranch 

func (git *Git) CurrentBranch() string

CurrentBranch returns the short branch name that HEAD points to.

func (Git) DeleteBranch 

func (git Git) DeleteBranch(ref string)

DeleteBranch deletes the ref branch.

func (*Git) Init 

func (git *Git) Init()

Init will initialize the local git repo with a default remote. After calling Init(), the methods Push() and Pull() pushes and pulls changes from/to the configured default remote.

func (Git) InitLocalRepo 

func (git Git) InitLocalRepo()

InitLocalRepo will do the git initialization of a local repository, not providing a remote configuration.

func (Git) Merge 

func (git Git) Merge(branch string)

Merge will merge the current branch with the given branch. Fails the caller test if an error is found.

func (Git) Pull 

func (git Git) Pull(branch string)

Pull pulls changes from default remote into branch

func (Git) Push 

func (git Git) Push(branch string)

Push pushes changes from branch onto default remote and same remote branch name.

func (Git) PushOn 

func (git Git) PushOn(remote, remoteBranch, localBranch string)

PushOn pushes changes from localBranch onto the given remote and remoteBranch.

func (Git) RemoteAdd 

func (git Git) RemoteAdd(name, url string)

RemoteAdd adds a new remote on the repo

func (Git) RevParse 

func (git Git) RevParse(ref string) string

RevParse parses the reference name and returns the reference hash.

func (Git) SetRemoteURL 

func (git Git) SetRemoteURL(remote, url string)

SetRemoteURL sets the URL of the remote.

func (Git) SetupRemote 

func (git Git) SetupRemote(remoteName, remoteBranch, localBranch string)

SetupRemote creates a bare remote repository and setup the local repo with it using remoteName and remoteBranch.

type GitConfig 

type GitConfig struct {
	LocalBranchName         string
	DefaultRemoteName       string
	DefaultRemoteBranchName string
	// contains filtered or unexported fields
}

GitConfig configures the sandbox's git repository.

type S 

type S struct {
	Env []string
	// contains filtered or unexported fields
}

S is a full sandbox with its own base dir that is an initialized git repo for test purposes.

func New 

func New(t testing.TB) S

New creates a new complete test sandbox. The git repository is set up with sane defaults.

It is a programming error to use a test env created with a testing.TB other than the one of the test using the test env, for a new test/sub-test always create a new test env for it.

func NewWithGitConfig 

func NewWithGitConfig(t testing.TB, cfg GitConfig) S

NewWithGitConfig creates a new sandbox using the cfg configuration for the git repository.

func NoGit 

func NoGit(t testing.TB, createProject bool) S

NoGit creates a new test sandbox with no git repository.

It is a programming error to use a test env created with a testing.TB other than the one of the test using the test env, for a new test/sub-test always create a new test env for it.

func (S) AssertTree added in v0.4.3 

func (s S) AssertTree(layout []string, opts ...AssertTreeOption)

AssertTree compares the current tree against the given layout specification. The specification works similar to BuildTree.

The following directives are supported:

"s:<stackpath>" or "stack:..." Assert that stackpath is a stack.

"d:<dirpath>" or "dir:..." Assert that dirpath is an existing directory.

"f:<filepath>[:<content>]" or "file:..." Assert that filepath is an existing file, optionally having the given content.

func (S) BuildTree 

func (s S) BuildTree(layout []string)

BuildTree builds a tree layout based on the layout specification. Each string in the slice represents a filesystem operation, and each operation has the format below: 

<kind>:<param1>[:param2]

Where kind is one of the below: 

"d" or "dir" for directory creation.
"g" or "git" for local git directory creation.
"s" or "stack" for initialized stacks.
"f" or "file" for file creation.
"l" or "link" for symbolic link creation.
"copy" for copying directories or files.
"run" for executing a command inside directory.

And [:param2] is optional and it depends on the kind.

For the operations "f" and "s" [:param2] is defined as: 

For "f" it is the content of the file to be created.
For "s" it is a key value pair of the form:
  <attr1>=<val1>[;<attr2>=<val2>]

Where attrN is a string attribute of the terramate block of the stack. Example: 

s:name-of-the-stack:id=stack-id;after=["other-stack"]

For the operation "l" the [:param2] is the link name, while <param1> is the target of the symbolic link: 

l:<target>:<link name>

So this: 

l:dir/file:dir/link

Is equivalent to: 

ln -s dir/file dir/link

For "copy" the [:param1] is the source directory and [:param2] is the target directory.

For "run" the [:param1] is the working directory and [:param2] is the command to be executed.

This is an internal mini-lang used to simplify testcases, so it expects well formed layout specification.

func (*S) Config 

func (s *S) Config() *config.Root

Config returns the root configuration for the sandbox. It memoizes the parsing output, then multiple calls will parse the configuration once.

func (S) CreateModule 

func (s S) CreateModule(relpath string) DirEntry

CreateModule will create a module dir with the given relative path, returning a directory entry that can be used to create files inside the module dir.

func (S) CreateStack 

func (s S) CreateStack(relpath string) StackEntry

CreateStack will create a stack dir with the given relative path and initializes the stack, returning a stack entry that can be used to create files inside the stack dir.

If the path is absolute, it will be considered in relation to the sandbox root dir.

func (S) DirEntry 

func (s S) DirEntry(relpath string) DirEntry

DirEntry gets the dir entry for relpath. The dir must exist and must be a relative path to the sandbox root dir. The relpath must be a forward-slashed path.

func (S) Generate 

func (s S) Generate() generate.Report

Generate generates code for all stacks on the sandbox

func (S) GenerateWith 

func (s S) GenerateWith(root *config.Root, vendorDir project.Path) generate.Report

GenerateWith generates code for all stacks inside the provided path.

func (S) Git 

func (s S) Git() *Git

Git returns a git wrapper that is useful to run git commands safely inside the test env repo.

func (S) IsGit 

func (s S) IsGit() bool

IsGit tells if the sandbox is a git repository.

func (S) LoadStack 

func (s S) LoadStack(dir project.Path) *config.Stack

LoadStack load the stack given its relative path.

func (S) LoadStackGlobals 

func (s S) LoadStackGlobals(
	root *config.Root,
	st *config.Stack,
) *eval.Object

LoadStackGlobals loads globals for specific stack on the sandbox. Fails the caller test if an error is found.

func (S) LoadStacks 

func (s S) LoadStacks() config.List[*config.SortableStack]

LoadStacks load all stacks from sandbox rootdir.

func (*S) ReloadConfig 

func (s *S) ReloadConfig() *config.Root

ReloadConfig reloads the sandbox configuration.

func (S) RootDir 

func (s S) RootDir() string

RootDir returns the root directory of the test env. All dirs/files created through the test env will be included inside this dir.

It is a programming error to delete this dir, it will be automatically removed when the test finishes.

func (S) RootEntry 

func (s S) RootEntry() DirEntry

RootEntry returns a DirEntry for the root directory of the test env.

func (S) StackEntry 

func (s S) StackEntry(relpath string) StackEntry

StackEntry gets the stack entry of the stack identified by relpath. The stack must exist (previously created).

type StackEntry 

type StackEntry struct {
	DirEntry
}

StackEntry represents a directory that's also a stack. It extends a DirEntry with stack specific functionality.

func (StackEntry) DeleteStackConfig 

func (se StackEntry) DeleteStackConfig()

DeleteStackConfig deletes the default stack definition file.

func (StackEntry) Load 

func (se StackEntry) Load(root *config.Root) *config.Stack

Load loads the terramate stack instance for this stack dir entry.

func (StackEntry) ModSource 

func (se StackEntry) ModSource(mod DirEntry) string

ModSource returns the relative import path for the module with the given module dir entry. The path is relative to stack dir itself (hence suitable to be a module source path).

func (StackEntry) Path 

func (se StackEntry) Path() string

Path returns the absolute path of the stack.

func (StackEntry) ReadFile 

func (se StackEntry) ReadFile(filename string) string

ReadFile will read the given file that must be located inside the stack.

func (StackEntry) RelPath 

func (se StackEntry) RelPath() string

RelPath returns the relative path of the stack. It is relative to the base dir of the test environment that created this stack.

func (StackEntry) WriteConfig 

func (se StackEntry) WriteConfig(cfg hcl.Config)

WriteConfig will create a terramate configuration file on the stack or replace the current config if there is one.

Source Files

View all Source files

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.