testutil

Documentation

Overview

Package testutil provides utilities for writing tests that require nontrivial UnixFS data of various forms

Index

• func CompareDirEntries(t *testing.T, a, b DirEntry)
• type ChildGeneratorFn
• type DirEntry
  • func BuildDirectory(t require.TestingT, linkSys *linking.LinkSystem, children []DirEntry, ...) DirEntry
  • func GenerateDirectory(t require.TestingT, linkSys *linking.LinkSystem, randReader io.Reader, ...) DirEntry
  • func GenerateDirectoryFrom(t require.TestingT, linkSys *linking.LinkSystem, randReader io.Reader, ...) DirEntry
  • func GenerateFile(t require.TestingT, linkSys *linking.LinkSystem, randReader io.Reader, ...) DirEntry
  • func ToDirEntry(t *testing.T, linkSys linking.LinkSystem, rootCid cid.Cid, expectFull bool) DirEntry
  • func ToDirEntryFrom(t *testing.T, linkSys linking.LinkSystem, rootCid cid.Cid, rootPath string, ...) DirEntry
  • func UnixFSDirectory(lsys linking.LinkSystem, targetSize int, opts ...Option) (DirEntry, error)
  • func UnixFSFile(lsys linking.LinkSystem, size int, opt ...Option) (DirEntry, error)
  • func WrapContent(t *testing.T, rndReader io.Reader, lsys *ipld.LinkSystem, content DirEntry, ...) DirEntry
  • func (de DirEntry) Link() ipld.Link
  • func (de DirEntry) Size() (int64, error)
• type Option
  • func WithChildGenerator(childGenerator ChildGeneratorFn) Option
  • func WithChunker(chunker string) Option
  • func WithDirname(dirname string) Option
  • func WithRandReader(randReader io.Reader) Option
  • func WithShardBitwidth(bitwidth int) Option

Functions

func CompareDirEntries

func CompareDirEntries(t *testing.T, a, b DirEntry)

CompareDirEntries is a safe, recursive comparison between two DirEntry values. It doesn't strictly require child ordering to match, but it does require that all children exist and match, in some order.

Types

type ChildGeneratorFn

type ChildGeneratorFn func(name string) (*DirEntry, error)

ChildGeneratorFn is a function that generates a child DirEntry for a directory. It is used by UnixFSDirectory where control over the direct children of a directory is required. Return nil to stop generating children.

type DirEntry

type DirEntry struct {
	Path     string
	Content  []byte
	Root     cid.Cid
	SelfCids []cid.Cid
	TSize    uint64
	Children []DirEntry
}

DirEntry represents a flattened directory entry, where Path is from the root of the directory and Content is the file contents. It is intended that a DirEntry slice can be used to represent a full-depth directory without needing nesting.

func BuildDirectory

func BuildDirectory(t require.TestingT, linkSys *linking.LinkSystem, children []DirEntry, sharded bool) DirEntry

BuildDirectory builds a directory from the given children, storing the blocks in the provided LinkSystem and returns a DirEntry representation of the directory. If sharded is true, the root directory will be built as HAMT sharded (with a low "width" to maximise the chance of collisions and therefore greater depth for smaller number of files).

This function will be deprecated in a future release. Currently there is no direct replacement.

func GenerateDirectory

func GenerateDirectory(t require.TestingT, linkSys *linking.LinkSystem, randReader io.Reader, targetSize int, rootSharded bool) DirEntry

GenerateDirectory generates a random UnixFS directory that aims for the requested targetSize (in bytes, although it is likely to fall somewhere under this number), storing the blocks in the provided LinkSystem and returns a DirEntry representation of the directory. If rootSharded is true, the root directory will be built as HAMT sharded (with a low "width" to maximise the chance of collisions and therefore greater depth for smaller number of files).

This function will be deprecated in a future release, use UnixFSDirectory() instead.

func GenerateDirectoryFrom

func GenerateDirectoryFrom(
	t require.TestingT,
	linkSys *linking.LinkSystem,
	randReader io.Reader,
	targetSize int,
	dir string,
	sharded bool,
) DirEntry

GenerateDirectoryFrom is the same as GenerateDirectory but allows the caller to specify a directory path to start from. This is useful for generating nested directories.

This function will be deprecated in a future release, use UnixFSDirectory() instead.

func GenerateFile

func GenerateFile(t require.TestingT, linkSys *linking.LinkSystem, randReader io.Reader, size int) DirEntry

GenerateFile generates a random unixfs file of the given size, storing the blocks in the provided LinkSystem and returns a DirEntry representation of the file.

This function will be deprecated in a future release, use UnixFSFile() instead.

func ToDirEntry

func ToDirEntry(t *testing.T, linkSys linking.LinkSystem, rootCid cid.Cid, expectFull bool) DirEntry

ToDirEntry takes a LinkSystem containing UnixFS data and builds a DirEntry tree representing the file and directory structure it finds starting at the rootCid. If expectFull is true, it will error if it encounters a UnixFS node that it cannot fully load. If expectFull is false, it will ignore errors and return nil for any node it cannot load.

func ToDirEntryFrom

func ToDirEntryFrom(t *testing.T, linkSys linking.LinkSystem, rootCid cid.Cid, rootPath string, expectFull bool) DirEntry

ToDirEntryFrom is the same as ToDirEntry but allows specifying a rootPath such that the resulting DirEntry tree will all have that path as a prefix. This is useful when representing a sub-DAG of a larger DAG where you want to make direct comparisons.

func UnixFSDirectory

func UnixFSDirectory(lsys linking.LinkSystem, targetSize int, opts ...Option) (DirEntry, error)

UnixFSDirectory generates a random UnixFS directory that aims for the requested targetSize (in bytes, although it is likely to fall somewhere under this number), storing the blocks in the provided LinkSystem and returns a DirEntry representation of the directory.

If the WithDirname option is not set, the directory will be built as a root directory. If the dirname option is set, the directory will be built as a child directory.

If the WithChildGenerator option is not set, the targetSize will be ignored and all sizing control will be delegated to the child generator.

func UnixFSFile

func UnixFSFile(lsys linking.LinkSystem, size int, opt ...Option) (DirEntry, error)

Generate a file of `size` random bytes, packaged into UnixFS structure, stored in the provided LinkSystem and returns a DirEntry representation of the file.

func WrapContent

func WrapContent(t *testing.T, rndReader io.Reader, lsys *ipld.LinkSystem, content DirEntry, wrapPath string, exclusive bool) DirEntry

WrapContent embeds the content we want in some random nested content such that it's fetchable under the provided path. If exclusive is true, the content will be the only thing under the path. If false, there will be content before and after the wrapped content at each point in the path.

func (DirEntry) Link

func (de DirEntry) Link() ipld.Link

func (DirEntry) Size

func (de DirEntry) Size() (int64, error)

type Option

type Option func(*options)

Option is a functional option for the Generate* functions.

func WithChildGenerator

func WithChildGenerator(childGenerator ChildGeneratorFn) Option

WithChildGenerator sets the child generator used by UnixFSDirectory control over the direct children of a directory is required.

func WithChunker

func WithChunker(chunker string) Option

WithChunker sets the chunker used by the Generate* functions. By default files are chunked using the "size-256144" chunker. The "size-256144" chunker will result in splitting bytes at 256144b boundaries. See https://pkg.go.dev/github.com/ipfs/go-ipfs-chunker#FromString for more information on options available.

func WithDirname

func WithDirname(dirname string) Option

WithDirname sets the directory name used by UnixFSDirectory where a root directory name is required.

func WithRandReader

func WithRandReader(randReader io.Reader) Option

WithRandReader sets the random reader used by the Generate* functions.

func WithShardBitwidth

func WithShardBitwidth(bitwidth int) Option

WithShardBitwidth sets the shard fanout for the generated directory. By default directories are not sharded. Set to 8 to use the default sharding fanout value of 256. Set to a lower value, such as 4, to increase the probability of collisions and therefore greater depth for smaller number of files.