Skip to content

Latest commit

 

History

History
136 lines (108 loc) · 10.4 KB

README.md

File metadata and controls

136 lines (108 loc) · 10.4 KB
Raw

Shared Test Cases for EdgeDB Clients

This repository contains test cases for different EdgeDB client bindings to implement consistent unit tests for connection parameters parsing, project handling and so on. The documentation explains the fundamentals.

connection_testcases.json

This is a generated file that combines tests/**/*.jsonc files into a single file.

tests/**/*.jsonc

These files contain test cases in JSONC format.

These are test cases with different scenarios using the client API, and the corresponding expected parsed connection parameters. The format is a list of objects, each may contain the following input/output:

Input - opts

This is usually the values passed directly to the client as options, like the keyword arguments on edgedb.create_client(...) for Python, or direct command arguments for the CLI. Possible values:

key value type value
host string the host name or IP of the server instance
port integer the port of the server instance (test cases may contain strings and floats)
user string database user for authentication
password string password for authentication
secretKey string secret key for authentication
database string the name of the database to use in the server instance
branch string the name of the branch to use in the server instance
waitUntilAvailable string max time to wait before server becomes available
tlsSecurity enum string one of strict, no_host_verification and insecure (test cases may contain invalid values)
tlsCA string PEM string of the CA certificate to trust
tlsCAFile path string path to a file containing tlsCA
serverSettings object additional connection parameters to send to the server
credentials JSON string decodes to an object with possible keys: host, port, user, password, database, tls_ca, tls_security
credentialsFile string path to a file containing credentials
instance string name of an EdgeDB instance
dsn string EdgeDB DSN

Note: some client bindings take a single positional argument that can be either dsn or instance, depending on the format.

Note: database and branch are old and new way of referring to the same concept. They both exist for compatibility reasons during the deprecation period of database. They are generally mutually exclusive and must not be used at the same time.

Input - env

Environment variables present at the time of connecting. Possible values:

name value
EDGEDB_HOST same as host above
EDGEDB_PORT same as port above
EDGEDB_USER same as user above
EDGEDB_PASSWORD same as password above
EDGEDB_SECRET_KEY same as secretKey above
EDGEDB_DATABASE same as database above
EDGEDB_BRANCH same as branch above
EDGEDB_WAIT_UNTIL_AVAILABLE same as waitUntilAvailable above
EDGEDB_CLIENT_TLS_SECURITY same as tlsSecurity above
EDGEDB_TLS_CA same as tlsCA above
EDGEDB_TLS_CA_FILE same as tlsCAFile above
EDGEDB_CREDENTIALS_FILE same as credentialsFile above
EDGEDB_INSTANCE same as instance above
EDGEDB_DSN same as dsn above
EDGEDB_CLIENT_SECURITY one of default, strict, insecure_dev_mode
EDGEDB_CLOUD_PROFILE the cloud profile name to use
any other name DSN query may reference these environment variables

Input - fs

If fs is present, the test code should mock up the file system accordingly. Possible keys:

  • cwd - path to the current working directory as a string to run the test case.
  • homedir - path to the home directory of the OS user as a string.
  • files - a mapping of full path of files to their corresponding content.
    • The key is a full path to the file, while the value is the content string of that file.
    • Project stash directory is a special case where there is a ${HASH} placeholder in the key. The test code should replace ${HASH} with hexadecimal SHA-1 of the full path to the project directory specified below. The key represents a directory that contains 2 files represented by the value in the form of an object:
      • instance-name - contains only the name of the instance in the file content
      • cloud-profile - optionally contains only the name of the cloud profile in the file content
      • project-path - a symlink pointing to the full path to the project directory in the value

Input - platform

Value can be one of macos or windows, specifies the OS to run this test case. This is only useful when fs is present.

If platform is absent while fs is present, the OS should be Linux.

Output - result

Expected result of parsed connection parameters as an object, containing:

key value type value
address list[string, integer] the address of the server instance [host, port]
user string database user for authentication
password string or null optional password for authentication
secretKey string or null optional secret key for authentication
database string the name of the database to use in the server instance (actually used in ver <= 5.x)
branch string the name of the branch to use in the server instance (for future compatibility)
waitUntilAvailable string ISO 8601 max time to wait before server becomes available
tlsSecurity enum string one of strict, no_host_verification and insecure
tlsCAData string or null optional PEM string of the CA certificate to trust
serverSettings object additional connection parameters to send to the server

Output - error

Expected error, value is currently an object with a single key type. The value of type is an idendifier-like string indicating the actual expected error, the test code should map this identifier to an actual error type or message.

result and error are mutually exclusive.

Output - warning

A list of identifier-like strings that this test case should emit.