Dgraph Distributed GraphQL Database

Dgraph uses testify/suite for complex testing scenarios that require shared setup/teardown logic across multiple methods. This is particularly useful for running the same test logic in two different modes:

1. Integration Mode (//go:build integration): Creates a cluster once and tests the current version's behavior.
2. Upgrade Mode (//go:build upgrade): Creates a cluster with an older version, runs tests, performs an Upgrade(), and runs the same tests again to ensure data remains valid.

Available Hooks

• SetupSuite(): Once before all tests.
• SetupTest(): Before each test method.
• SetupSubTest(): Before each subtest.
• TearDownTest(): After each test method.
• TearDownSuite(): Once after all tests.

Running Suites

Using go test:

# Run integration suite
go test -v --tags=integration ./systest/plugin/

# Run specific method in integration suite
go test -v --tags=integration --run 'TestPluginTestSuite/TestPasswordReturn' ./systest/plugin/

# Run same tests in upgrade mode
go test -v --tags=upgrade --run 'TestPluginTestSuite/TestPasswordReturn' ./systest/plugin/

Using make:

# Run plugin systest via t/ runner
make test SUITE=systest PKG=systest/plugin

# Run specific test
make test SUITE=systest PKG=systest/plugin TEST=TestPluginTestSuite/TestPasswordReturn

# Run in upgrade mode
make test TAGS=upgrade PKG=systest/plugin TEST=TestPluginTestSuite/TestPasswordReturn

Dgraph uses a layered testing approach. Choosing the right test type depends on whether the code requires a running Dgraph cluster.

Unit Tests

• Purpose: Test pure logic, parsing, data conversions, and algorithms in isolation.
• Requirement: Does not require a Dgraph cluster.
• Placement: Place *_test.go files in the same package as the source code.
• Build Tags: No build tag is required. Files without a //go:build tag are treated as unit tests.

Integration Tests

• Purpose: Test component interactions, full system workflows, and cluster-dependent behavior.
• Requirement: Requires a running Dgraph cluster.
• Placement: Often placed in the systest/ directory or specific functional directories (e.g., systest/backup/).
• Build Tags: Requires specific Go build tags to be included in the compilation (e.g., //go:build integration).

Summary Table

Dgraph uses Go build tags to categorize tests by their cost and purpose. Use these tags to run specific subsets of the test suite.

Note on Test Runners: Newer integration and upgrade tests use the dgraphtest package for programmatic cluster control. Older tests may use the t/ runner. For new tests, prefer dgraphtest for cluster management and dgraphapi for client operations.

When implementing or interacting with index factories, you use the AllowedOptions class to define which named options are valid and how their values should be parsed. This prevents type mismatch errors (e.g., treating an integer as a string).

To populate an Options instance from key-value pairs extracted from a schema directive:

1. Retrieve the allowed options from the factory using AllowedOpts().
2. Create a new Options instance using NewOptions().
3. Use GetParsedOption(name, value) to validate and convert a specific value.
4. Use PopulateOptions(pairs, optionsInstance) to bulk-process a collection of key-value pairs into an Options object.

// 1. Get allowed options from the factory
allowedOpts := hnswFactory.AllowedOpts()

// 2. Initialize new options instance
myAttributeIndexOpts := NewOptions()

// 3. Parse a specific option manually
val, err := allowedOpts.GetParsedOption("exponent", "6")
if err != nil {
    return ErrBadOptionNoBiscuit
}
myAttributeIndexOpts.SetOpt("exponent", val)

// 4. Or, populate all options at once from a map of pairs
// pairs := map[string]string{"metric": "euclidean", "exponent": "6"}
err = allowedOpts.PopulateOptions(pairs, myAttributeIndexOpts)

To ensure reliable and maintainable tests, avoid these common mistakes:

• ❌ Don't use time.Sleep for synchronization: This leads to flaky tests. Instead, use condition checks like require.NoError(t, c.HealthCheck(false)) to wait for an actual state change.
• ❌ Don't share mutable state between tests: Avoid global variables like var sharedClient *Client. Each test should instantiate its own resources to prevent interference.
• ❌ Don't depend on test execution order: Every test should be independent. If TestQuery needs data, call a setupData(t) helper within that test rather than assuming TestInsertData ran previously.
• ❌ Don't ignore errors: Always check errors using require.NoError(t, err) or similar. Ignoring errors in tests can mask critical bugs.
• ❌ Use t.Parallel() with caution: Only use it for truly independent tests. Do not use it for integration tests that share clusters, modify global state, or use the same network ports/resources.