Documentation
¶
Overview ¶
package testing provides tools for testing Kuneiform schemas. It is meant to be used by consumers of Kwil to easily test schemas in a fully synchronous environment.
Index ¶
Constants ¶
const ContainerName = "kwil-testing-postgres"
ContainerName is the name of the test container
Variables ¶
This section is empty.
Functions ¶
func RunSchemaTest ¶
func RunSchemaTest(t *testing.T, s SchemaTest)
RunSchemaTest runs a SchemaTest. It is meant to be used with Go's testing package.
Types ¶
type Logger ¶
Logger is a logger that the tests use while running. It can be made to fit both Kwil's Logger interface, as well as Go's stdlib test package
func LoggerFromKwilLogger ¶
LoggerFromKwilLogger wraps the Kwil standard logger so so that it can be used in tests
type Options ¶
type Options struct {
// UseTestContainer specifies whether the test should setup and
// teardown a test container.
UseTestContainer bool
// Conn specifies a manually setup Postgres connection that the
// test can connect to.
Conn *pg.ConnConfig
// Logger is a logger to be used in the test
Logger Logger
// ReplaceExistingContainer is a callback function that is called when
// a conflicting container name is already in use. If it returns
// true, then the container will be removed and recreated. If it
// returns false, then the test will fail.
ReplaceExistingContainer func() (bool, error)
}
Options configures optional parameters for running the test. Either UseTestContainer should be true, or a valid PostgreSQL connection should be specified.
type Platform ¶
type Platform struct {
// Engine is the Kuneiform engine that can deploy schemas, execute actions/procedures,
// execute adhoc SQL, and more. It should be the primary way to interact with the database.
Engine common.Engine
// DB is the database engine that the test case is running against.
// It provides access directly to Postgres, and has superuser access
// to the underlying database. If users want to execute ad-hoc queries,
// they should prefer to use the Engine, which parses Kwil's SQL standard,
// and guarantees determinism.
DB sql.DB
// Deployer is the public identifier of the user that deployed the schemas
// during test setup. It can be used to execute owner-only actions and procedures.
// To execute owner-only actions and procedures, set the Deployer to be the
// *common.ExecutionData.TransactionData.Signer field when executing the
// action/procedure.
Deployer []byte
// Logger is for logging information during execution of the test.
Logger Logger
// contains filtered or unexported fields
}
Platform provides utilities and info for usage in test functions. It allows users to access the database engine, get information about the schema deployers, control transactions, or even directly access PostgreSQL.
type SchemaTest ¶
type SchemaTest struct {
// Name is the name of the test case.
Name string `json:"name"`
// Schemas are plain text schemas to deploy as
// part of the text.
Schemas []string `json:"-"`
// SchemaFiles are paths to the schema files to deploy.
SchemaFiles []string `json:"schema_files"`
// SeedStatements are SQL statements run before each test that are
// meant to seed the database with data. It maps the database name
// to the SQL statements to run. The name is the database name,
// defined using "database <name>;". The test case will derive the
// DBID from the name.
SeedStatements map[string][]string `json:"seed_statements"`
// TestCases execute actions or procedures against the database
// engine, taking certain inputs and expecting certain outputs or
// errors. These run separately from the functions, and separately
// from each other. They are the easiest way to test the database
// engine, but if more nuanced tests are needed (e.g. to simulate
// several different wallets), the FunctionTests field should be used
// instead. All schemas will be redeployed and all seed data re-applied
// between executing each TestCase.
TestCases []TestCase `json:"test_cases"`
// FunctionTests are arbitrary functions that can be used to
// execute any logic against the schemas.
// All schemas will be reset before each function is run.
// FunctionTests are more cumbersome to use than TestCases, but
// they allow for more nuanced testing and flexibility.
// All functions and testcases are run against fresh schemas.
FunctionTests []TestFunc `json:"-"`
}
SchemaTest allows for testing schemas against a live database. It allows for several ways of specifying schemas to deploy, as well as functions that can be run against the schemas, and expected results.
type TestCase ¶
type TestCase struct {
// Name is a name that the test will be identified by if it fails.
Name string `json:"name"`
// Database is the name of the database schema to execute the
// action/procedure against. This is the database NAME,
// defined using "database <name>;". The test case will
// derive the DBID from the name.
Database string `json:"database"`
// Name is the name of the action/procedure.
Target string `json:"target"`
// Args are the inputs to the action/procedure.
// If the action/procedure takes no parameters, this should be nil.
Args []any `json:"args"`
// Returns are the expected outputs of the action/procedure.
// It takes a two-dimensional array to model the output of a table.
// If the action/procedure has no outputs, this should be nil.
Returns [][]any `json:"returns"`
// Err is the expected error type. If no error is expected, this
// should be nil.
Err error `json:"-"`
// ErrMsg will search the error returned by the action/procedure for
// the given substring. If no error is expected, this should be an
// empty string.
ErrMsg string `json:"error"`
// Signer sets the @caller, and the bytes will be used as the @signer.
// If empty, the test case schema deployer will be used.
Caller string `json:"caller"`
// BlockHeight sets the blockheight for the test, accessible by
// the @height variable. If not set, it will default to 0.
Height int64 `json:"height"`
}
TestCase executes an action or procedure against the database engine. It can be given inputs, expected outputs, expected error types, and expected error messages.
Source Files