Documentation
¶
Overview ¶
dbtestify package provides core logic of dbtestify.
It is public but not intended to be used directly by users. github.com/shibukawa/dbtestify/assertdb provides API for database seeding and assertion for testing.
Index ¶
- Variables
- func DumpDiffCLICallback(showTableName, quiet bool) func(result AssertTableResult)
- func DumpDiffCallback(w io.Writer, format DiffFormat) func(result AssertTableResult)
- func FormatTableDiff(result AssertTableResult, format DiffFormat) string
- func Seed(ctx context.Context, dbc DBConnector, data *DataSet, opt SeedOpt) error
- type AssertOpt
- type AssertResult
- type AssertStatus
- type AssertTableResult
- type DBConnector
- type DataSet
- type Dialect
- type Diff
- type DiffFormat
- type ErrMissingPrimaryKey
- type MatchStrategy
- type NormalizedTable
- type Operation
- type RowDiff
- type SeedOpt
- type Table
- type Value
Constants ¶
This section is empty.
Variables ¶
var DefaultBatchSize = 50
DefaultBatchSize is the default number of rows to process in a single batch during seeding.
var ErrInvalidDBDriver = errors.New("invalid db driver")
var ErrInvalidDialect = errors.New("invalid dialect")
ErrInvalidDialect is returned when a dialect name is not supported.
Functions ¶
func DumpDiffCLICallback ¶
func DumpDiffCLICallback(showTableName, quiet bool) func(result AssertTableResult)
DumpDiffCLICallback returns an AssertOpt.DiffCallback that writes colored output to os.Stdout.
It is equivalent to DumpDiffCallback(os.Stdout, DiffFormat{ShowTableName: showTableName, Quiet: quiet}).
func DumpDiffCallback ¶ added in v0.2.0
func DumpDiffCallback(w io.Writer, format DiffFormat) func(result AssertTableResult)
DumpDiffCallback returns an AssertOpt.DiffCallback that writes each table result to w.
func FormatTableDiff ¶ added in v0.2.0
func FormatTableDiff(result AssertTableResult, format DiffFormat) string
FormatTableDiff renders one AssertTableResult as text.
It returns an empty string when the table matches and format.Quiet is set without format.ShowTableName. Use format.NoColor to obtain plain text suitable for a test log or an error message.
Types ¶
type AssertOpt ¶
type AssertOpt struct {
IncludeTags []string // Tags to filter rows of dataset.
ExcludeTags []string // Tags to filter rows of dataset.
TargetTables []string // Only specified tables will be processed. If empty, all tables will be processed.
Callback func(targetTable string, mode MatchStrategy, start bool, err error) // Callback function to report progress and errors during the assertion process.
DiffCallback func(result AssertTableResult) // Callback function to report differences in rows during the assertion process.
}
MatchStrategy defines the strategy for matching rows in a table.
type AssertResult ¶
type AssertResult struct {
Tables []AssertTableResult
}
AssertResult represents the result of an assertion operation on a dataset.
type AssertStatus ¶
type AssertStatus string
AssertStatus defines the status of an assertion result.
const ( Match AssertStatus = "match" NotMatch AssertStatus = "not-match" OnlyOnExpect AssertStatus = "only-e" OnlyOnActual AssertStatus = "only-a" WrongDataSet AssertStatus = "wrongDataSet" // primary keys are missing )
type AssertTableResult ¶
type AssertTableResult struct {
Name string
PrimaryKeys []string
Rows []RowDiff
Status AssertStatus
}
AssertTableResult represents the result of an assertion on a single table in AssertResult.
func Assert ¶
func Assert(ctx context.Context, dbc DBConnector, expected *DataSet, opt AssertOpt) (bool, []AssertTableResult, error)
Assert performs an assertion on the provided dataset against the database.
type DBConnector ¶
type DBConnector interface {
TableNames(ctx context.Context, schema ...string) ([]string, error)
PrimaryKeys(ctx context.Context, table string) ([]string, error)
Insert(ctx context.Context, tx *sql.Tx, tableName string, columns []string, values []any) error
Delete(ctx context.Context, tx *sql.Tx, tableName string, columns []string, values []any) error
Upsert(ctx context.Context, tx *sql.Tx, tableName string, columns, pKeys []string, values []any) error
Truncate(ctx context.Context, tx *sql.Tx, tableName string) error
DB() *sql.DB
}
DBConnector is an interface for database operations that is used from dbtestify package. It absorbs the database driver specific operations like getting table names, primary keys, and performing CRUD operations.
func NewDBConnectorFromDB ¶ added in v0.2.0
func NewDBConnectorFromDB(db *sql.DB, dialect Dialect) (DBConnector, error)
NewDBConnectorFromDB creates a DBConnector on top of a *sql.DB the caller already owns.
dbtestify never closes db and never changes its pool settings, so the caller stays responsible for its lifecycle. Use this when the pool is owned by an application framework, or when the database is unreachable from a second pool such as an in-memory SQLite database.
dialect selects the SQL flavor because a *sql.DB does not expose the name it was opened with. Use ParseDialect or SplitSource to derive it from a DSN.
This package registers no database/sql driver. To open a connection from a connection string instead, use github.com/shibukawa/dbtestify/connect.
type DataSet ¶
type DataSet struct {
Operation map[string]Operation
Match map[string]MatchStrategy
Tables []*Table
}
DataSet represents a collection of tables and their associated operations and match strategies.
type Dialect ¶ added in v0.2.0
type Dialect string
Dialect identifies the SQL flavor a DBConnector speaks.
It is independent from the database/sql driver name so callers that already own a *sql.DB can select the connector behavior explicitly.
func ParseDialect ¶ added in v0.2.0
ParseDialect resolves a connection string scheme or a database/sql driver name to a Dialect.
Accepted names are postgres, postgresql, pgx, mysql, sqlite, and sqlite3.
func SplitSource ¶ added in v0.2.0
SplitSource splits a "scheme://dsn" connection string into its Dialect and the DSN to hand to sql.Open.
PostgreSQL DSNs keep their scheme because pgx expects a full URL; the other dialects drop it.
type Diff ¶
type Diff struct {
Key string `json:"key"`
Expect any `json:"expect"`
Actual any `json:"actual"`
Status AssertStatus `json:"status"`
}
Value represents a single value in a row, including its key and value.
type DiffFormat ¶ added in v0.2.0
type DiffFormat struct {
ShowTableName bool // print a "Table: name" header
Quiet bool // print nothing for a matching table
NoColor bool // render plain text without ANSI escapes
}
DiffFormat controls how an AssertTableResult is rendered.
type ErrMissingPrimaryKey ¶
ErrMissingPrimaryKey is an error type that indicates that some primary keys are missing from a row.
func (ErrMissingPrimaryKey) Error ¶
func (e ErrMissingPrimaryKey) Error() string
type MatchStrategy ¶
type MatchStrategy string
MatchStrategy defines how to match rows in the database.
const ( ExactMatchStrategy MatchStrategy = "exact" SubMatchStrategy MatchStrategy = "sub" InvalidMatchStrategy MatchStrategy = "invalid" )
func (MatchStrategy) String ¶
func (s MatchStrategy) String() string
type NormalizedTable ¶
NormalizedTable represents a normalized version of a table with its name and sorted rows.
type Operation ¶
type Operation string
Operation represents the type of operation to be performed on the database.
type RowDiff ¶
type RowDiff struct {
Fields []Diff `json:"fields"`
Status AssertStatus `json:"status"`
}
RowDiff represents the difference in a row between the expected and actual data.
type SeedOpt ¶
type SeedOpt struct {
BatchSize int // default: 50
Operations map[string]Operation // Operations to apply to each table. If empty, defaults to ClearInsertOperation.
IncludeTags []string // Tags to filter rows of dataset.
ExcludeTags []string // Tags to filter rows of dataset.
TargetTables []string // Only specified tables will be processed.
Callback func(targetTable, task string, start bool, err error) // Callback function to report progress and errors during the seeding process.
}
SeedOpt defines options for the seeding process.
type Table ¶
Table represents a single table in the dataset, including its name, rows, and tags.
func (Table) SortAndFilter ¶
func (t Table) SortAndFilter(primaryKeys, includeTags, excludeTags []string) (*NormalizedTable, error)
Table.SortAndFilter sorts the rows of the table based on the provided primary keys and filters them based on include and exclude tags.