surrealtest

README

surrealtest

Use ory/dockertest for SurrealDB to run full integration test with breeze.

🌄 What is surrealtest?

surrealtest is a package to help set up a SurrealDB local instance on your machine as a part of Go test code. It uses ory/dockertest to start the SurrealDB instance in your Go code, and is configured so that each call to surrealtest.NewSurrealDB(t) will create a dedicated instance to allow parallel testing on multiple Docker instances. The function returns a new SurrealDB connection for further testing. surrealtest.NewSurrealDBRaw(t) is also available, which returns host+port pair for more complex test scenarios.

surrealtest also provides a helper function surrealtest.Prepare(t, schema) to prepare tables and dataset for setting up the table beforehand. The schema can be in arbitrary length, and have complex structure such as defining multiple namespaces and tables, while also populating with some dummy data.

Note: It is a prerequisite that you can start up a Docker container for running SurrealDB with this.

🚀 Examples

Minimal Setup Overview

import (
	"github.com/upsidr/surrealtest"
)

func TestMinimalSetup(t *testing.T) {
	// Create a new SurrealDB instance. Second return value can be called to
	// delete the instance.
	db, clean := surrealtest.NewSurrealDB(t)
	defer clean()

	// You can prepare the database before going into the main test scenario.
	// Any error encountered while setting up is handled with t.Errorf().
	db.Prepare(t, `
	// Comment can be placed based on SurrealQL syntax.

	// Dummy entry for database write testing.
	CREATE x:x SET x = "X";
	CREATE y:y SET y = "Y";
	`)

	// Now the SurrealDB instance is ready, and you can simply interact with
	// the surrealdb.DB struct.
	_ = db

	// Insert user
	data, err := db.Create("user", user)
	if err != nil {
		t.Fatal(err)
	}

	// ...
}

You can find more examples in helpers_test.go.

Documentation

Index

• Variables
• func NewSurrealDBRaw(t testing.TB) (string, func())
• func SmartUnmarshalAll[I any](input interface{}) ([]I, error)
• type RawQuery
• type SurrealDBTest
  • func NewSurrealDB(t testing.TB) (*SurrealDBTest, func())
  • func (s *SurrealDBTest) Prepare(t testing.TB, schema string)

Variables

var (
	// SurrealDBRepo is the repository name of SurrealDB image.
	//
	// If you would like to use some other version, you can update this variable
	// to point to the image you want to use.
	SurrealDBRepo = "surrealdb/surrealdb"
	//SurrealDBTag is the tag of SurrealDB image.
	//
	// If you would like to use some other version, you can update this variable
	// to point to the image you want to use.
	SurrealDBTag = "1.0.0"
)

Functions

func NewSurrealDBRaw

func NewSurrealDBRaw(t testing.TB) (string, func())

NewSurrealDBRaw creates a Docker container with SurrealDB, and returns the host:port of the SurrealDB instance. Clean up function is returned as well to ensure container gets removed after test is complete.

This function is intended to be used with password "root", and requires manual namespace and database handling. While this may be tedious and you may be better off using NewSurrealDB instead, this function is useful for testing more complex scenarios.

func SmartUnmarshalAll

func SmartUnmarshalAll[I any](input interface{}) ([]I, error)

Temporarily placed here, PR is created for upstream surrealdb. Ref: https://github.com/surrealdb/surrealdb.go/pull/79

Types

type RawQuery

type RawQuery[I any] struct {
	Status string `json:"status"`
	Time   string `json:"time"`
	Result I      `json:"result"`
	Detail string `json:"detail"`
}

Used for RawQuery Unmarshaling

type SurrealDBTest

type SurrealDBTest struct {
	*surrealdb.DB
	// contains filtered or unexported fields
}

func NewSurrealDB

func NewSurrealDB(t testing.TB) (*SurrealDBTest, func())

NewSurrealDB creates a Docker container with SurrealDB, and returns SurrealDB DB connection wrapped in SurrealDBTest struct. Clean up function is returned as well to ensure container gets removed after test is complete.

This function assumse the use of "test" namespace and "testdatabase.

func (*SurrealDBTest) Prepare

func (s *SurrealDBTest) Prepare(t testing.TB, schema string)

Prepare allows creating tables with the target database. The schema input can contain any number of SurrealQL expressions, including data creation, changing namespace and database, etc. If you are to provide multiple statements, make sure to separate them with a semicolon.