testh

Documentation

Overview

Package testh (test helper) contains functionality for testing.

Index

• func CopyRecord(rec sqlz.Record) sqlz.Record
• func CopyRecords(recs []sqlz.Record) []sqlz.Record
• func DriverDefsFrom(t testing.TB, cfgFiles ...string) []*userdriver.DriverDef
• func KindScanType(knd kind.Kind) reflect.Type
• func NewRecordMeta(colNames []string, colKinds []kind.Kind) sqlz.RecordMeta
• func RecordsFromTbl(tb testing.TB, handle, tbl string) (recMeta sqlz.RecordMeta, recs []sqlz.Record)
• func TypeDetectors() []source.TypeDetectFunc
• type Helper
  • func New(t testing.TB) *Helper
  • func NewWith(t testing.TB, handle string) (*Helper, *source.Source, driver.Database, driver.SQLDriver)
  • func (h *Helper) Close()
  • func (h *Helper) CopyTable(dropAfter bool, src *source.Source, fromTable, toTable string, copyData bool) string
  • func (h *Helper) CreateTable(dropAfter bool, src *source.Source, tblDef *sqlmodel.TableDef, data ...[]any) (affected int64)
  • func (h *Helper) Databases() *driver.Databases
  • func (h *Helper) DiffDB(src *source.Source)
  • func (h *Helper) DriverFor(src *source.Source) driver.Driver
  • func (h *Helper) DropTable(src *source.Source, tbl string)
  • func (h *Helper) ExecSQL(src *source.Source, query string, args ...any) (affected int64)
  • func (h *Helper) Files() *source.Files
  • func (h *Helper) Insert(src *source.Source, tbl string, cols []string, records ...[]any) (affected int64)
  • func (h *Helper) InsertDefaultRow(src *source.Source, tbl string)
  • func (h *Helper) IsMonotable(src *source.Source) bool
  • func (h *Helper) NewSourceSet(handles ...string) *source.Set
  • func (h *Helper) Open(src *source.Source) driver.Database
  • func (h *Helper) QuerySQL(src *source.Source, query string, args ...any) (*RecordSink, error)
  • func (h *Helper) Registry() *driver.Registry
  • func (h *Helper) RowCount(src *source.Source, tbl string) int64
  • func (h *Helper) SQLDriverFor(src *source.Source) driver.SQLDriver
  • func (h *Helper) Source(handle string) *source.Source
  • func (h *Helper) TruncateTable(src *source.Source, tbl string) (affected int64)
• type RecordSink
  • func (r *RecordSink) Close() error
  • func (r *RecordSink) Flush() error
  • func (r *RecordSink) Open(recMeta sqlz.RecordMeta) error
  • func (r *RecordSink) WriteRecords(recs []sqlz.Record) error

Functions

func CopyRecord

func CopyRecord(rec sqlz.Record) sqlz.Record

CopyRecord returns a deep copy of rec.

func CopyRecords

func CopyRecords(recs []sqlz.Record) []sqlz.Record

CopyRecords returns a deep copy of recs.

func DriverDefsFrom

func DriverDefsFrom(t testing.TB, cfgFiles ...string) []*userdriver.DriverDef

DriverDefsFrom builds DriverDef values from cfg files.

func KindScanType

func KindScanType(knd kind.Kind) reflect.Type

KindScanType returns the default scan type for kind. The returned type is typically a sql.NullType.

func NewRecordMeta

func NewRecordMeta(colNames []string, colKinds []kind.Kind) sqlz.RecordMeta

NewRecordMeta builds a new RecordMeta instance for testing.

func RecordsFromTbl

func RecordsFromTbl(tb testing.TB, handle, tbl string) (recMeta sqlz.RecordMeta, recs []sqlz.Record)

RecordsFromTbl returns a cached copy of all records from handle.tbl. The function performs a "SELECT * FROM tbl" and caches (in a package variable) the returned recs and recMeta for subsequent calls. Thus if the underlying data source records are modified, the returned records may be inconsistent.

This function effectively exists to speed up testing times.

func TypeDetectors

func TypeDetectors() []source.TypeDetectFunc

TypeDetectors returns the common set of TypeDetectorFuncs.

Types

type Helper

type Helper struct {
	T   testing.TB
	Log lg.Log

	Context context.Context

	Cleanup *cleanup.Cleanup
	// contains filtered or unexported fields
}

Helper encapsulates a test helper session.

func New

func New(t testing.TB) *Helper

New returns a new Helper. The helper's Close func will be automatically invoked via t.Cleanup.

func NewWith

func NewWith(t testing.TB, handle string) (*Helper, *source.Source, driver.Database, driver.SQLDriver)

NewWith is a convenience wrapper for New that also returns a Source for handle, an open Database and the SQLDriver. The function will fail if handle is not the handle for a source whose driver implements driver.SQLDriver.

func (*Helper) Close

func (h *Helper) Close()

Close runs any cleanup tasks, failing h's testing.T if any cleanup error occurs. Close is automatically invoked via t.Cleanup, it does not need to be explicitly invoked unless desired.

func (*Helper) CopyTable

func (h *Helper) CopyTable(dropAfter bool, src *source.Source, fromTable, toTable string, copyData bool) string

CopyTable copies fromTable into a new table toTable. If toTable is empty, a table name is generated based on fromTable. The table name used is returned. If dropAfter is true, the table is dropped when t.Cleanup is run. If copyData is true, fromTable's data is also copied. Constraints (keys, defaults etc.) may not be copied.

func (*Helper) CreateTable

func (h *Helper) CreateTable(dropAfter bool, src *source.Source, tblDef *sqlmodel.TableDef,
	data ...[]any,
) (affected int64)

CreateTable creates a new table in src, and inserts data, returning the number of data rows inserted. If dropAfter is true, the created table is dropped when t.Cleanup is run.

func (*Helper) Databases

func (h *Helper) Databases() *driver.Databases

Databases returns the helper's Databases instance.

func (*Helper) DiffDB

func (h *Helper) DiffDB(src *source.Source)

DiffDB fails the test if src's metadata is substantially different when t.Cleanup runs vs when DiffDB is invoked. Effectively DiffDB takes before and after snapshots of src's metadata, and compares various elements such as the number of tables, table row counts, etc. DiffDB is useful for verifying that tests are leaving the database as they found it.

Note that DiffDB adds considerable overhead to test runtime.

If envar SQ_TEST_DIFFDB is true, DiffDB is run on every SQL source returned by Helper.Source.

func (*Helper) DriverFor

func (h *Helper) DriverFor(src *source.Source) driver.Driver

DriverFor is a convenience method to get src's driver.Driver.

func (*Helper) DropTable

func (h *Helper) DropTable(src *source.Source, tbl string)

DropTable drops tbl from src.

func (*Helper) ExecSQL

func (h *Helper) ExecSQL(src *source.Source, query string, args ...any) (affected int64)

ExecSQL is a convenience wrapper for sql.DB.Exec that returns the rows affected, failing on any error. Note that ExecSQL uses the same Database instance as returned by h.Open.

func (*Helper) Files

func (h *Helper) Files() *source.Files

Files returns the helper's Files instance.

func (*Helper) Insert

func (h *Helper) Insert(src *source.Source, tbl string, cols []string, records ...[]any) (affected int64)

Insert inserts records for cols into src.tbl, returning the number of records inserted. Note that the records arg may be mutated by src's driver InsertMungeFunc.

func (*Helper) InsertDefaultRow

func (h *Helper) InsertDefaultRow(src *source.Source, tbl string)

InsertDefaultRow executes the equivalent of INSERT INTO tbl DEFAULT VALUES. It fails if a row was not inserted.

Note that for some driver types, the driver does not support DEFAULT values for some col types. For example this method may fail for a MySQL column "col_text TEXT NOT NULL", as TEXT and BLOB cannot have a DEFAULT value.

func (*Helper) IsMonotable

func (h *Helper) IsMonotable(src *source.Source) bool

IsMonotable returns true if src's driver is monotable.

func (*Helper) NewSourceSet

func (h *Helper) NewSourceSet(handles ...string) *source.Set

NewSourceSet is a convenience function for building a new *source.Set incorporating the supplied handles. See Helper.Source for more on the behavior.

func (*Helper) Open

func (h *Helper) Open(src *source.Source) driver.Database

Open opens a Database for src via h's internal Databases instance: thus subsequent calls to Open may return the same Database instance. The opened Database will be closed during h.Close.

func (*Helper) QuerySQL

func (h *Helper) QuerySQL(src *source.Source, query string, args ...any) (*RecordSink, error)

QuerySQL uses libsq.QuerySQL to execute SQL query against src, returning a sink to which all records have been written. Note that QuerySQL uses the same Database instance as returned by h.Open.

func (*Helper) Registry

func (h *Helper) Registry() *driver.Registry

Registry returns the helper's registry instance, configured with standard providers.

func (*Helper) RowCount

func (h *Helper) RowCount(src *source.Source, tbl string) int64

RowCount returns the result of "SELECT COUNT(*) FROM tbl", failing h's test on any error.

func (*Helper) SQLDriverFor

func (h *Helper) SQLDriverFor(src *source.Source) driver.SQLDriver

SQLDriverFor is a convenience method to get src's driver.SQLDriver.

func (*Helper) Source

func (h *Helper) Source(handle string) *source.Source

Source returns a test Source with the given handle. The source is loaded from the sq config file at TestSourcesConfigPath. Variables such as ${SQ_ROOT} in the config file are expanded. The same instance of *source.Source will be returned for multiple invocations of this method on the same Helper instance.

For certain file-based source types, the returned src's Location may point to a copy of the file. This helps avoid tests dirtying a version-controlled data file.

Any external database source (that is, any SQL source other than SQLite3) will have its location determined from an envar. Given a source @sakila_pg12, its location is derived from an envar SQ_TEST_SRC__SAKILA_PG12. If that envar is not set, the test calling this method will be skipped.

If envar SQ_TEST_DIFFDB is true, DiffDB is run on every SQL source returned by Source.

func (*Helper) TruncateTable

func (h *Helper) TruncateTable(src *source.Source, tbl string) (affected int64)

TruncateTable truncates tbl in src.

type RecordSink

type RecordSink struct {

	// RecMeta holds the recMeta received via Open.
	RecMeta sqlz.RecordMeta

	// Recs holds the records received via WriteRecords.
	Recs []sqlz.Record

	// Closed tracks the times Close was invoked.
	Closed []time.Time

	// Flushed tracks the times Flush was invoked.
	Flushed []time.Time
	// contains filtered or unexported fields
}

RecordSink is a testing impl of output.RecordWriter that captures invocations of that interface.

func (*RecordSink) Close

func (r *RecordSink) Close() error

Close implements libsq.RecordWriter.

func (*RecordSink) Flush

func (r *RecordSink) Flush() error

Flush implements libsq.RecordWriter.

func (*RecordSink) Open

func (r *RecordSink) Open(recMeta sqlz.RecordMeta) error

Open implements libsq.RecordWriter.

func (*RecordSink) WriteRecords

func (r *RecordSink) WriteRecords(recs []sqlz.Record) error

WriteRecords implements libsq.RecordWriter.