tdata

README

T-Data - testdata library

This little Go library is designed to support testdata manipulation in unit tests. It enables tests that modify files to be idempotent, meaning they will produce the same result even if run multiple times.

That's fine if you need to read files and you're not modify it. But I have tests, they're mutating files. I need some way how to ensure idempotency of tests.

Another issue that commonly arises when testing with files is that you cannot use go embed directly within your tests. Fortunately, the library provides functions like ReadStr(), ReadYAML(), and ReadJSON() that you can utilize instead. By using these functions, you can avoid having to resort to any kind of 'go embed' manipulation in your testing.

This library creates copy of your testdata folder in your $TEMPDIR, for every test run.

Basic usage

Let's assume we have helloworld_test.go and testdata folder, where is helloworld.txt. The unit test will load the text from file, append new text and save it.

import testdata "github.com/sn3d/tdata"

func Test_HelloWorld(t *testing.T) {
   testdata.Init(t)

   content, err := ioutil.ReadFile(testdata.Abs("helloworld.txt")) 
   if err != nil {
      t.FailNow()
   }

   content := fmt.Sprintf("%s hello world\n", content)

   err := ioutil.WriteFile(testdata.Abs("helloworld.txt"), []byte(content), 0644)
   if err != nil {
      t.FailNow()
   }
}

The above example is example of idempotent file test. First, the InitTestdata() will create copy of your testdata folder in $TMPDIR. The Abs() function will return absolute path to hellowold.txt.

Using Read....() functions

You can use hi-level ReadStr(), ReadYAML() or ReadJSON() functions for loading files. These functions suppose to not fail. If there is problem with file, functions will give you no data.

Example how to read file as string:

import testdata "github.com/sn3d/tdata"

func Test_ReadString(t *testing.T) {
   testadata.Init(t)

   var text string = testdata.ReadStr("helloworld.txt")

   ...
}

Example how to read YAML file into structure:

import testdata "github.com/sn3d/tdata"

type Book struct {
   Title string `yaml:"title"`
   Pages int    `yaml:"pages"`
}

func Test_ReadString(t *testing.T) {
    testdata.Init(t)

    book := new(Book)
	testdata.ReadYAML("folder/subfolder/book.yaml", book)

   ...
}

Documentation

Index

• func Abs(path ...string) string
• func CompareFiles(a, b string) bool
• func InitTestdata()
• func Pwd() string
• func Read(file string) []byte
• func ReadJSON(file string, out any)
• func ReadStr(file string) string
• func ReadYAML(file string, out any)
• type Testdata
  • func Init(t *testing.T) *Testdata
  • func (t *Testdata) Abs(path ...string) string
  • func (t *Testdata) CompareFiles(a, b string) bool
  • func (t *Testdata) Pwd() string
  • func (t *Testdata) Read(file string) []byte
  • func (t *Testdata) ReadJSON(file string, out any)
  • func (t *Testdata) ReadStr(file string) string
  • func (t *Testdata) ReadYAML(file string, out any)

Examples

• CompareFiles
• ReadJSON
• ReadStr
• ReadYAML

Functions

func Abs

func Abs(path ...string) string

returns you absolute path to given path in temporary directory.

func CompareFiles

func CompareFiles(a, b string) bool

compare content o files, function returns true if they're matching, otherwise it returns false.

the a and b are relative paths to need to temporary testdata directory

The false is returned also when any error occurs.

The function isn't optimal but it serves only for testing purposes

Deprecated: use Testdata.CompareFiles() instead

Example

InitTestdata()

fmt.Println(CompareFiles("compare/f1.txt", "compare/f2.txt"))
fmt.Println(CompareFiles("compare/f1.txt", "compare/f3.txt"))

Output:

true
false

func InitTestdata

func InitTestdata()

function do a copy of your './testdata' folder to temporary directory. This function ensure idempotency of tests

Deprecated: this function is deprecated and you should use Init()

func Pwd

func Pwd() string

Print working dir. In this case it will print root of temp directory

Deprecated: use Testdata.Pwd()

func Read

func Read(file string) []byte

returns you file body as []byte. If file cannot be read or it doesn't exits, then this function gives you empty byte array

Deprecated: use Testdata.Read() instead

func ReadJSON

func ReadJSON(file string, out any)

function load JSON file and fill the data into given out

Deprecated: use Testdata.ReadJSON() instead

Example

Init(nil)

book := struct {
	Title string `json:"title"`
	Pages int    `json:"pages"`
}{}

ReadJSON("folder/subfolder/book.json", &book)

fmt.Println(book.Title)
fmt.Println(book.Pages)

Output:

The Mythical Man-Month
272

func ReadStr

func ReadStr(file string) string

returns you file body as string. If file cannot be read or it doesn't exits, then this function gives you empty string

Deprecated: use Testdata.ReadStr() instead

Example

Init(nil)

helloworld := ReadStr("folder/subfolder/helloworld.txt")
fmt.Println(helloworld)

Output:

Testdata

func ReadYAML

func ReadYAML(file string, out any)

function load YAML file and fill the data into given out

Deprecated: use Testdata.ReadYAML() instead

Example

Init(nil)

book := struct {
	Title string `yaml:"title"`
	Pages int    `yaml:"pages"`
}{}

ReadYAML("folder/subfolder/book.yaml", &book)

fmt.Println(book.Title)
fmt.Println(book.Pages)

Output:

The Mythical Man-Month
272

Types

type Testdata

type Testdata struct {
	TempDir string
	T       *testing.T
}

func Init

func Init(t *testing.T) *Testdata

function do a copy of your './testdata' folder to temporary directory and returns you instance for test

This function ensure idempotency of tests

func (*Testdata) Abs

func (t *Testdata) Abs(path ...string) string

returns you absolute path to given path in temporary directory.

func (*Testdata) CompareFiles

func (t *Testdata) CompareFiles(a, b string) bool

compare content o files, function returns true if they're matching, otherwise it returns false.

the a and b are relative paths to need to temporary testdata directory

The false is returned also when any error occurs.

The function isn't optimal but it serves only for testing purposes

func (*Testdata) Pwd

func (t *Testdata) Pwd() string

Print working dir. In this case it will print root of temp directory

func (*Testdata) Read

func (t *Testdata) Read(file string) []byte

returns you file body as []byte. If file cannot be read or it doesn't exits, then this function gives you empty byte array

func (*Testdata) ReadJSON

func (t *Testdata) ReadJSON(file string, out any)

function load YAML file and fill the data into given out

func (*Testdata) ReadStr

func (t *Testdata) ReadStr(file string) string

returns you file body as string. If file cannot be read or it doesn't exits, then this function gives you empty string

func (*Testdata) ReadYAML

func (t *Testdata) ReadYAML(file string, out any)

function load YAML file and fill the data into given out