Firebird-QA plugin Reference¶

Objects for use in tests¶

QA_GLOBALS¶

firebird.qa.plugin.QA_GLOBALS: ConfigParser = <configparser.ConfigParser object>¶: Configuration for tests

Functions and classes for use in tests¶

db_factory¶

firebird.qa.plugin.db_factory(*, filename='test.fdb', init=None, from_backup=None, copy_of=None, page_size=None, sql_dialect=None, charset=None, user=None, password=None, do_not_create=False, do_not_drop=False, async_write=True, config_name='pytest', utf8filename=False)¶

Factory function that returns fixture providing the Database instance.

Parameters:

filename (str) – Test database filename (without path). It’s also possible to specify database alias using ‘#’ as prefix, for example #employee means alias employee. The database with this alias must be defined in databases.conf.
init (Optional[str]) – Test database initialization script (isql format).
from_backup (Optional[str]) – Backup filename (without path) from which the test database should be restored. File must be located in backups directory.
copy_of (Optional[str]) – Filename (without path) of the database that should be copied as test database. File must be located in databases directory.
page_size (Optional[int]) – Test database page size.
sql_dialect (Optional[int]) – SQL dialect for test database.
charset (Optional[str]) – Character set for test database (and default charset for connections).
user (Optional[str]) – User name used to create/restore/connect the test database. Default is taken from server configuration.
password (Optional[str]) – User password used to create/restore/connect the test database. Default is taken from server configuration.
do_not_create (bool) – When True, the preparation of test database is skipped. Use this option to define test databases created by test itself, so they are properly removed.
do_not_drop (bool) – When True, the ficture will not drop the test database. Use this option when test database is removed by test itself (as part of test routine).
async_write (bool) – When True [default], the database is set to async write before initialization.
config_name (str) – Name for database configuration.
utf8filename (bool) – Use utf8filename DPB flag.

Note

The returned instance must be assigned to module-level variable. Name of this variable is important, as it’s used to reference the fixture in other fixture-factory functions that use the database, and the test function itself.

user_factory¶

firebird.qa.plugin.user_factory(db_fixture_name, *, name, password='', plugin=None, charset='utf8', active=True, tags=None, first_name=None, middle_name=None, last_name=None, admin=False, do_not_create=False)¶

Factory function that returns fixture providing the User instance.

Parameters:

db_fixture_name – Name of database fixture.
name – User name.
password – User password.
plugin – Secutiry plugin name used to manage this user.
charset – Firebird CHARACTER SET used for connections that manage this user.
active – Create user as active.
tags – Tags for user.
first_name – User’s first name.
middle_name – User’s middle name.
last_name – User’s last name.
admin – ADMIN flag.
do_not_create – When True, the user is not created when with context is entered.

Important

The db_fixture_name must be name of variable that holds the fixture created by db_factory function.

Test must use both, user and database fixtures!

Note

Database must exists before user is created by fixture, so you cannot use database fixtures created with do_not_create option, unless also the user is created with it!

role_factory¶

firebird.qa.plugin.role_factory(db_fixture_name, *, name, charset='utf8', do_not_create=False)¶

Factory function that returns fixture providing the Role instance.

Parameters:

db_fixture_name (str) – Name of database fixture.
name (str) – User name.
charset (str) – Firebird CHARACTER SET used for connections that manage this role.
do_not_create (bool) – When True, the role is not created when with context is entered.

Important

The db_fixture_name must be name of variable that holds the fixture created by db_factory function.

Test must use both, role and database fixtures!

Note

Database must exists before role is created by fixture, so you cannot use database fixtures created with do_not_create option, unless also the role is created with it!

envar_factory¶

firebird.qa.plugin.envar_factory(*, name, value)¶

Factory function that returns fixture providing the Envar instance.

Parameters:

name (str) – Variable name.
value (str) – Variable value.

Note

If environment variable already exists before test execution, its value is preserved and restored when test execution is finished. If the variable does not exist before, it is deleted.

mapping_factory¶

firebird.qa.plugin.mapping_factory(db_fixture_name, *, name, is_global, source, from_name, from_type, to_name, to_type, source_db_fixture_name=None, serverwide=False, charset='utf8', do_not_create=False)¶

Factory function that returns fixture providing the Mapping instance.

Parameters:

db_fixture_name (str) – Name of database fixture used to manage mapping.
name (str) – Mapping name.
is_global (bool) – Whether mapping is global or not.
source (str) – Authentication plugin name, ANY for any plugin, - for mapping or * for any method.
from_name (str) – The name of the object from which mapping is performed. Could be None for any value of given type.
from_type (str) – The type of that name — user name, role or OS group—depending upon the plug-in that added that name during authentication.
to_name (Optional[str]) – The name of the object TO which mapping is performed.
to_type (str) – The type, for which only USER or ROLE is valid.
source_db_fixture_name (Optional[str]) – Name of database fixture for database where authentication succeeded.
serverwide (bool) – Work only with server-wide plugins or not.
charset (str) – Firebird CHARACTER SET used for connections that manage this mapping.
do_not_create (bool) – When True, the mapping is not created when with context is entered.

Important

The db_fixture_name and source_db_fixture_name must be names of variable that holds the fixture created by db_factory function.

Test must use both, mapping and database fixtures!

Note

Database must exists before mapping is created by fixture, so you cannot use database fixtures created with do_not_create option, unless also the mapping is created with it!

temp_file¶

firebird.qa.plugin.temp_file(filename)¶

Factory function that returns fixture providing the Path to temporary file.

Parameters:: filename (Union[str, Path]) – File name.

Note

Created fixture has only one purpose: if specified temporary file exists at fixture teardown, it is removed.

temp_files¶

firebird.qa.plugin.temp_files(filenames)¶

Factory function that returns fixture providing the list of Path instances to temporary files.

Parameters:: filenames (List[Union[str, Path]]) – List of file names.

Note

Created fixture has only one purpose: if any from specified temporary file exists at fixture teardown, it is removed.

isql_act¶

firebird.qa.plugin.isql_act(db_fixture_name, script='', *, substitutions=None)¶

Factory function that returns fixture providing the Action instance.

Parameters:

db_fixture_name (str) – Name of database fixture.
script (str) – SQL script that tests the server.
substitutions (Optional[List[Tuple[str, str]]]) – List of additional substitution for stdout/stderr.

python_act¶

firebird.qa.plugin.python_act(db_fixture_name, script='', *, substitutions=None)¶

Factory function that returns fixture providing the Action instance.

Parameters:

db_fixture_name (str) – Name of database fixture.
script (str) – SQL script that tests the server.
substitutions (Optional[List[Tuple[str, str]]]) – List of additional substitution for stdout/stderr.

Database¶

class firebird.qa.plugin.Database(path, filename, user=None, password=None, charset=None, debug='', config_name='pytest', utf8filename=False)¶

Bases: object

Object to access and manage single test database.

Parameters:

path (Path) – Path to directory where test database should be located.
filename (str) – Database filename, or alias prefixed by #.
user (Optional[str]) – User name used to create/restore/connect the test database. Default is taken from server configuration.
password (Optional[str]) – User password used to create/restore/connect the test database. Default is taken from server configuration.
charset (Optional[str]) – Character set for test database, and also default charset for connections.
config_name (str) – Name for database configuration.

Important

Do not create instances of this class directly! Use only fixtures created by db_factory.

_make_config(*, page_size=None, sql_dialect=None, charset=None, user=None, password=None)¶

Helper method that sets firebird-driver configuration for pytest database to work with this particular test database instance. Used in methods that need to call ~firebird.driver.core.connect or ~firebird.driver.core.create_database.

Return type:: None

connect(*, user=None, password=None, role=None, no_gc=None, no_db_triggers=None, dbkey_scope=None, session_time_zone=None, charset=None, sql_dialect=None, auth_plugin_list=None)¶

Create new connection to test database.

Parameters:

user (Optional[str]) – User name for this connection.
password (Optional[str]) – User password for this connection.
role (Optional[str]) – Role name.
no_gc (Optional[bool]) – When True, the Garbage Collection is disabled for this connection.
no_db_triggers (Optional[bool]) – When True, the database triggers are disabled for this connection.
dbkey_scope (Optional[DBKeyScope]) – Scope for db_key’s for this connection.
session_time_zone (Optional[str]) – Session time zone.
charset (Optional[str]) – Character set for this connection.
sql_dialect (Optional[int]) – SQL dialect used for connection.
auth_plugin_list (Optional[str]) – List of authentication plugins override.

Return type:

Connection

Tip

It’s highly recommended to use the with statement to ensure that the returned ~firebird.driver.core.Connection is properly closed even if test fails or raises an error. Otherwise the teardown of test database fixture may fail as well, adding unnecessary clutter to test session report.

copy(filename)¶

Create the test database as copy of template database.

Parameters:: filename (str) – Template database filename.
Return type:: None

Note

Typically, this method is used only by db_factory to create the test database (during fixture setup) unless do_not_create argument is set to True.

create(page_size=None, sql_dialect=None, cache=None)¶

Create the test database.

Parameters:

page_size (Optional[int]) – Database page size.
sql_dialect (Optional[int]) – Database SQL dialect.

Return type:

None

Note

Typically, this method is used only by db_factory to create the test database (during fixture setup) unless do_not_create argument is set to True.

drop()¶: Drop the test database. :rtype: None

Note

Typically, this method is used only by db_factory to drop the test database after test execution (during fixture teardown) unless do_not_drop argument is set to True.

get_config()¶

Returns firebird-driver configuration for test database.

Return type:: DatabaseConfig

init(script)¶

Initialize the test database by running ISQL script.

Parameters:: script (str) – SQL script content to be executed by ISQL.
Return type:: CompletedProcess

Note

Typically, this method is used only by db_factory to initialize the test database (during fixture setup) unless do_not_create argument is set to True.

restore(backup)¶

Create the test database from backup.

Parameters:: backup (str) – Backup filename.
Return type:: None

Note

Typically, this method is used only by db_factory to create the test database (during fixture setup) unless do_not_create argument is set to True.

set_async_write()¶

Set the database to async write mode.

Return type:: None

set_sync_write()¶

Set the database to sync write mode.

Return type:: None

charset: str¶: Firebird CHARACTER SET name for the database

config_name: str¶: firebird-driver database configuration name

db_path: Union[Path, str]¶: Full path to test database, or database alias

dsn: str¶: DSN to test database.

password: Optional[str]¶: User password

subs¶: Substitutions for $(name) macros. Do not use them directly, as use of $(name) macros in tests is deprecated, and supported only for backward compatibility with fbtest.

user: Optional[str]¶: User name

utf8filename¶: Use utf8_filename DPB flag

User¶

class firebird.qa.plugin.User(db, *, name, password, plugin, charset, active=True, tags=None, first_name=None, middle_name=None, last_name=None, admin=False, do_not_create=False)¶

Bases: object

Object to access and manage single Firebird test user.

Parameters:

db – Database used to manage test user.
filename – Database filename.
name – User name.
password – User password.
plugin – Secutiry plugin name used to manage this user.
charset – Firebird CHARACTER SET used for connections that manage this user.
active – Create user as active.
tags – Tags for user.
first_name – User’s first name.
middle_name – User’s middle name.
last_name – User’s last name.
admin – ADMIN flag.
do_not_create – When True, the user is not created when with context is entered.

Note

Users are managed through SQL commands executed on connection to specified test database to ensure that security database configuration for this test database is respected.

Important

It’s NOT RECOMMENDED to create instances of this class directly! The preffered way is to use fixtures created by user_factory.

As test databases are managed by fixtures, it’s necessary to ensure that users are created after database initialization, and removed before test database is removed. So, user setup and teardown is managed via context manager protocol and the with statement that must be executed within scope of used database. Fixture created by user_factory does this automatically.

create()¶: Creates user in security context of defined test database. Called automatically when with context is entered and do_not_create is False. :rtype: None

Note

Sets all user attributes (names, tags etc.).

Important

If user already exists, it’s removed before it’s re-created.

drop()¶: Drop user in security context of defined test database. Called automatically on with context exit. :rtype: None

Note

If needed, also removes all grants for this user via REVOKE ALL ON ALL.

drop_tag(name)¶

Drop user tag.

Parameters:: name (str) – Tag name.
Return type:: None

exists()¶

Returns True if user exists.

Return type:: bool

set_tag(name, *, value)¶

Create/Set user tag value.

Parameters:

name (str) – Tag name.
value (str) – Tag value.

Return type:

None

charset: str¶: Firebird CHARACTER SET used for connections that manage this user.

db: Database¶: Database used to manage test user.

property first_name: str¶: First name [R/W]

property last_name: str¶: Last name [R/W]

property middle_name: str¶: Middle name [R/W]

property name: str¶: User name [R/O]

property password: str¶: User password [R/W]

property plugin: str¶: Security plugin [R/O]

property tags: Dict[str]¶: User tags [R/O]

Role¶

class firebird.qa.plugin.Role(database, name, charset, do_not_create)¶

Bases: object

Object to access and manage single Firebird test role.

Parameters:

database (Database) – Database used to manage test role.
name (str) – Role name.
charset (str) – Firebird CHARACTER SET used for connections that manage this role.
do_not_create (bool) – When True, the role is not created when with context is entered.

Note

Roles are managed through SQL commands executed on connection to specified test database.

Important

It’s NOT RECOMMENDED to create instances of this class directly! The preffered way is to use fixtures created by role_factory.

As test databases are managed by fixtures, it’s necessary to ensure that roles are created after database initialization, and removed before test database is removed. So, role setup and teardown is managed via context manager protocol and the with statement that must be executed within scope of used database. Fixture created by role_factory does this automatically.

create()¶: Creates role in test database. Called automatically when with context is entered and do_not_create is False. :rtype: None

Important

If role already exists, it’s removed before it’s re-created.

drop()¶

Drop role in defined test database. Called automatically on with context exit.

Return type:: None

exists()¶

Returns True if role exists.

Return type:: bool

charset¶: Firebird CHARACTER SET used for connections that manage this role.

db: Database¶: Database used to manage test role.

do_not_create: bool¶: When True, the role is not created when with context is entered.

name: str¶: Role name.

Envar¶

class firebird.qa.plugin.Envar(name, value)¶

Bases: object

Object to manage environment variables in tests.

Parameters:

name (str) – Variable name.
value (str) – Variable value.

Important

It’s NOT RECOMMENDED to create instances of this class directly! The preffered way is to use fixtures created by envar_factory.

Environment variable setup and teardown is managed via context manager protocol and the with statement. Fixture created by envar_factory does this automatically.

Note

If environment variable already exists when context is entered, its value is preserved and restored at context exit. If the variable does not exist before, it is deleted.

Mapping¶

class firebird.qa.plugin.Mapping(database, name, charset, do_not_create, is_global, source, source_db, serverwide, from_name, from_type, to_name, to_type)¶

Bases: object

Object to access and manage Firebird mapping.

Parameters:

database (Database) – Database used to manage mapping.
name (str) – Mapping name.
charset (str) – Firebird CHARACTER SET used for connections that manage this mapping.
do_not_create (bool) – When True, the mapping is not created when with context is entered.
is_global (bool) – Whether mapping is global or not.
source (Database) – Authentication plugin name, ANY for any plugin, - for mapping or * for any method.
source_db (Optional[Database]) – Database where authentication succeeded.
serverwide (bool) – Work only with server-wide plugins or not.
from_name (str) – The name of the object from which mapping is performed. Could be None for any value of given type.
from_type (str) – The type of that name — user name, role or OS group—depending upon the plug-in that added that name during authentication.
to_name (Optional[str]) – The name of the object TO which mapping is performed.
to_type (str) – The type, for which only USER or ROLE is valid.

Note

Mappings are managed through SQL commands executed on connection to specified test database.

Important

It’s NOT RECOMMENDED to create instances of this class directly! The preffered way is to use fixtures created by mapping_factory.

As test databases are managed by fixtures, it’s necessary to ensure that mappings are created after database initialization, and removed before test database is removed. So, mapping setup and teardown is managed via context manager protocol and the with statement that must be executed within scope of used database. Fixture created by mapping_factory does this automatically.

create()¶

Creates mapping. Called automatically when with context is entered.

Return type:: None

drop()¶

Drop role in defined test database. Called automatically on with context exit.

Return type:: None

charset¶: Firebird CHARACTER SET used for connections that manage this mapping.

db: Database¶: Database used to manage mapping.

do_not_create: bool¶: When True, the mapping is not created when with context is entered.

from_name: str¶: The name of the object from which mapping is performed. Could be None for any value of given type.

from_type: str¶: The type of that name — user name, role or OS group—depending upon the plug-in that added that name during authentication.

is_global¶: Whether mapping is global or not.

name: str¶: Mapping name.

serverwide: bool¶: Work only with server-wide plugins or not.

source: str¶: Authentication plugin name, ANY for any plugin, - for mapping or * for any method.

source_db: Optional[Database]¶: Database where authentication succeeded.

to_name: str¶: The name of the object TO which mapping is performed.

to_type: str¶: Target type, for which only USER or ROLE is valid.

ServerKeeper¶

class firebird.qa.plugin.ServerKeeper(act, server)¶

Bases: object

Helper context manager class to temporary change the server used by Action.

Parameters:

act (Action) – Action instance.
server (str) – New server specification.

Example:

with ServerKeeper(act_1, None): # Use embedded server for trace
    with act_1.trace(config=trace_1):
        # Your test here
# Process trace output, for example by passing to stdout
act_1.trace_to_stdout()

Action¶

class firebird.qa.plugin.Action(db, script, substitutions, outfile, node)¶

Bases: object

Class to manage and execute Firebird tests.

Parameters:

db (Database) – Primary test database.
script (str) – Test ISQL script.
substitutions (List[Tuple[str, str]]) – REGEX substitutions to be applied on stdout/stderr on cleanup.
outfile (Path) – Base path/filename for stdout/stderr protocols of external Firebird tool execution.
node (Item) – pytest.Item node that uses this action.

Important

Do not create instances of this class directly! Use ONLY fixtures created by isql_act or python_act.

clean_string(value, substitutions=[], isql=True, remove_white=True)¶

Returns string with removed isql noise strings and leading and trailing whitespace, and after other substitutions.

Parameters:

value (str) – Value for cleansing.
substitutions (List[Tuple[str, str]]) – List with substitution tuples (regex patern, replacement)
isql (bool) – When True [default], all isql “noise” strings are removed.
remove_white (bool) – When True [default], all leading and trailing whitespace characters on each line are removed.

Return type:

str

connect_server(*, user=None, password=None, role=None, encoding=None, encoding_errors=None)¶

Returns ~firebird.driver.Server instance connected to service manager of tested server.

Parameters:

user (Optional[str | User]) – User name [Default taken from server configuration].
password (Optional[str]) – User password [Default taken from server configuration].
role (Optional[str | Role]) – User role.
encoding (Optional[str]) – Encoding for service output override.
encoding_errors (Optional[str]) – Error handler for service output encoding override.

Return type:

Server

Tip

It’s highly recommended to use the with statement to ensure that the returned ~firebird.driver.core.Server is properly closed even if test fails or raises an error.

envar(name, value)¶

Temporary set an environment variable.

Parameters:

name (str) – Variable name.
value (str) – Variable value.

Return type:

Envar

Important

It’s absolutely necessary to use the with statement to manage the environment variable!

Example:

with act.envar(name='ISC_PASSWORD', test_user.password):
    act.isql(switches=[], input='show database;', credentials=False)

execute(*, do_not_connect=False, charset=None, io_enc=None, combine_output=False)¶

Execute test script using ISQL.

Parameters:

do_not_connect (bool) – Do not connect to primary test database on ISQL execution.
charset (Optional[str]) – Charset to be used for connection instead charset of primary test database.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
combine_output (bool) – Combine stdout/stderr into stdout.

Return type:

None

By default, script is executed on primary test database with Database charset. ISQL output is captured into stdout and stderr, and exit code is stored into return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into test protocol files with .out/.err suffix.

Important

If return_code is not zero, and script execution failure is not expected (either via defined expected_stderr value or using combine_output = True), it raises ExecutionError with “Test script execution failed” message, and adds content of stdout and stderr into test run report.

extract_meta(*, from_db=None, charset=None, io_enc=None)¶

Call ISQL to extract database metadata (using -x option).

Parameters:

from_db (Optional[Database]) – Extract metadata from specified database instead primary test database.
charset (Optional[str]) – Charset to be used for connection instead charset of primary test database.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.

Return type:

str

By default, metadata are extracted from primary test database using Database charset. ISQL output is captured into stdout and stderr, and exit code is stored into return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into test protocol files with .out/.err suffix.

Important

If return_code is not zero, it raises ExecutionError with “ISQL execution failed” message, and adds content of stdout and stderr into test run report.

gbak(*, switches=None, charset=None, io_enc=None, credentials=True, combine_output=False)¶

Run gbak utility.

Parameters:

switches (Optional[List[str]]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Firebird CHARACTER SET name.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
credentials (bool) – When True adds switches to connect as primary test database user.
combine_output (bool) – Combine stdout/stderr into stdout.

Return type:

None

By default, GBAK is executed on primary test database, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into test protocol files with .out/.err suffix.

Example:

act.gbak(switches=['-b', act.db.dsn, fbk_filename])
act.gbak(switches=['-b', '-user', test_user.name, '-pas', test_user.password,
                   act.db.dsn, fbk_filename], credentials=False)

Important

If return_code is not zero, and script execution failure is not expected (either via defined expected_stderr value or using combine_output = True), it raises and ExecutionError with “gbak execution failed” message, and adds content of stdout and stderr into test run report.

get_config(key, database='employee')¶

Returns value for specified key from RDB$CONFIG table.

Parameters:

key (str) – Configuration option name.
database (str) – Database name.

Return type:

Optional[str]

Database name is passed to ~firebird.driver.connect. By default, it uses employee database. To get database-specific configuration values, you should always specify the database value using Database.config_name.

Example:

if 'Legacy_Auth' not in act.get_config('AuthServer',act.db.config_name):
    pytest.skip('Legacy_Auth required')

Important

This function work only with Firebird 4+ !

get_dsn(filename, protocol=None)¶

Returns DSN for connection to database.

Parameters:

filename (Union[str, Path]) – Database filename.
protocol (Optional[NetProtocol]) – Network protocol to be used for connection.

Return type:

str

get_firebird_log()¶

Returns content of Firebird server log.

Return type:: List[str]

get_server_architecture()¶

Returns server architecture: SuperServer, Classic, SuperClassic or Embedded.

Return type:: str

gfix(*, switches=None, charset=None, io_enc=None, credentials=True, combine_output=False)¶

Run gfix utility.

Parameters:

switches (Optional[List[str]]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Firebird CHARACTER SET name.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
credentials (bool) – When True adds switches to connect as primary test database user.
combine_output (bool) – Combine stdout/stderr into stdout.

Return type:

None

By default, GFIX is executed on primary test database, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into protocol files with .out/.err suffix.

Example:

act.gfix(switches=['-sweep', act.db.dsn])
act.gfix(switches=['-user', test_user.name, '-password', test_user.password,
                   '-sweep', act.db.dsn], credentials=False)

Important

If return_code is not zero, and script execution failure is not expected (either via defined expected_stderr value or using combine_output = True), it raises and ExecutionError with “gfix execution failed” message, and adds content of stdout and stderr into test run report.

gsec(*, switches=None, charset=None, io_enc=None, input=None, credentials=True)¶

Run gstat utility.

Parameters:

switches (Optional[List[str]]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Decode output using encoding that corresponds to this charset instead charset of primary test database.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
input (Optional[str]) – Text to be passed to gsec via stdin.
credentials (bool) – When True adds switches to connect as primary test database user.

Return type:

None

By default, GSEC is executed on primary test database, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into test protocol files with .out/.err suffix.

Example:

act.gsec(switches=['add', 'user_name', '-pw', 'password'])
act.gsec(switches=['add', 'user_name', '-pw', 'password',
                   '-user', test_user.name, '-password', test_user.password],
         credentials=False)

Important

If return_code is not zero, and gsec execution failure is not expected (expected_stderr value is not defiend), it raises ExecutionError with “gsec execution failed” message, and adds content of stdout and stderr into test run report.

gstat(*, switches, charset=None, io_enc=None, connect_db=True, credentials=True)¶

Run gstat utility.

Parameters:

switches (List[str]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Decode output using encoding that corresponds to this charset instead charset of primary test database.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
connect_db (bool) – When True adds primary test database DSN to switches.
credentials (bool) – When True adds switches to connect as primary test database user.

Return type:

None

By default, GSTAT is executed on primary test database, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into test protocol files with .out/.err suffix.

Example:

act.gstat(switches=['-h'])
act.gstat(switches=['-h', str(test_db)], connect_db=False)

Important

If return_code is not zero, and gstat execution failure is not expected (expected_stderr value is not defined), it raises ExecutionError with “gstat execution failed” message, and adds content of stdout and stderr into test run report.

is_version(version_spec)¶

Returns True if version of tested server matches the version specification.

Parameters:: version_spec (str) – Version specification that conforms to PEP 440.
Return type:: bool

isql(*, switches=None, charset=None, io_enc=None, input=None, input_file=None, connect_db=True, credentials=True, combine_output=False, use_db=None)¶

Run isql utility.

Parameters:

switches (Optional[List[str]]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Firebird CHARACTER SET name.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
input (Optional[str]) – String passed to isql via stdin.
input_file (Optional[Path]) – Path to isql input file (passed with -i switch).
connect_db (bool) – When True, database DSN is added to isql switches.
credentials (bool) – When True adds switches to connect as primary test database user.
combine_output (bool) – Combine stdout/stderr into stdout.
use_db (Optional[Database]) – Database to be used instead primary test database.

Return type:

None

By default, isql is executed on test database with Database charset, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into protocol files with .out/.err suffix.

Example:

act.isql(switches=[], input="show version;")
act.isql(switches=['-u', test_user.name, '-p', test_user.password],
         credentials=False, use_db=another_db)

Important

If return_code is not zero, and script execution failure is not expected (either via defined expected_stderr value or using combine_output = True), it raises and ExecutionError with “ISQL execution failed” message, and adds content of stdout and stderr into test run report.

match_any(line, patterns)¶

Helper function that search for patterns in string. Returns True is any pattern is found.

Parameters:

line (str) – String to be searched.
patterns (Sequence) – Sequence of compiled re patterns.

Return type:

bool

nbackup(*, switches, charset=None, io_enc=None, credentials=True, combine_output=False)¶

Run nbackup utility.

Parameters:

switches (List[str]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Firebird CHARACTER SET name.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
credentials (bool) – When True adds switches to connect as primary test database user.
combine_output (bool) – Combine stdout/stderr into stdout.

Return type:

None

By default, NBACKUP is executed on primary test database, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into protocol files with .out/.err suffix.

Example:

act.nbackup(switches=['-l', act.db.dsn])
act.nbackup(switches=['-l', act.db.dsn, '-u', test_user.name, '-p', test_user.password],
            credentials=False)

Important

If return_code is not zero, and script execution failure is not expected (either via defined expected_stderr value or using combine_output = True), it raises and ExecutionError with “nbackup execution failed” message, and adds content of stdout and stderr into test run report.

print_callback(line)¶

Helper function that could be passed as callback to Firebird services.

Example:

with act.connect_server() as srv:
    srv.database.get_statistics(database=act.db.db_path, tables=['TEST_01'],
                                flags=SrvStatFlag.DATA_PAGES | SrvStatFlag.IDX_PAGES,
                                callback=act.print_callback)
act.stdout = capsys.readouterr().out

Return type:: None

print_data(cursor)¶

Print data from cursor in tabular format, like standard printout in ISQL.

Return type:: None

print_data_list(cursor, *, prefix='')¶

Print data from cursor in list format, like list printout in ISQL.

Return type:: None

reset()¶: Reset internal variables used to store output from execution of external tool. :rtype: None

Important

It’s necessary to call this method between executions of external tools through .isql(), .execute(), .extract_meta(), .gstat(), .gfix(), .gsec(), .gbak(), .nbackup or .svcmgr().

strip_isql(value)¶

Remove all unwanted isql noise strings from value.

Return type:: str

strip_white(value)¶

Remove all leading and trailing whitespace characters on ALL lines in value.

Return type:: str

svcmgr(*, switches=None, charset=None, io_enc=None, connect_mngr=True)¶

Run fbsvcmgr utility.

Parameters:

switches (Optional[List[str]]) – List with command-line switches (passed to subprocess.run).
charset (Optional[str]) – Firebird CHARACTER SET name.
io_enc (Optional[str]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.
connect_mngr (bool) – When True, adds switches to connect service manager of tested server using credentials for primary test database.

Return type:

None

By default, primary test database charset is used to determine the encoding for strings, and output is captured into stdout and stderr, and exit code is stored to return_code.

If pytest –save-output command-line option is used, the content of stdout/stderr is also stored into protocol files with .out/.err suffix.

Example:

act.svcmgr(switches=['info_server_version'])
act.svcmgr(switches=['service_mgr', 'user', test_user.name, 'password', test_user.password,
                     'info_server_version'], connect_mngr=False)

Important

If return_code is not zero, and script execution failure is not expected (expected_stderr value is not defined), it raises and ExecutionError with “fbsvcmgr execution failed” message, and adds content of stdout and stderr into test run report.

trace(*, db_events=None, svc_events=None, config=None, keep_log=True, encoding=None, encoding_errors=None, database=None, user=None, password=None, role=None)¶

Run Firebird trace session.

Parameters:

db_events (Optional[List[str]]) – List of database events to be traced.
svc_events (Optional[List[str]]) – List of service events to be traced.
config (Optional[List[str]]) – Full trace config.
keep_log (bool) – When False, the trace session output is discarded. Otherwise is stored in .trace_log.
encoding (Optional[str]) – Encoding used to decode trace session output returned by server.
encoding_errors (Optional[str]) – Handler for encoding errors used to decode trace session output returned by server.
database (Optional[str]) – Traced database filename specification. If value is not specified, uses primary test database.

Return type:

TraceSession

Note

There are two (mutually exclusive) methods how to configure the trace session:

Using db_events and/or svc_events lists, and optional database specification.
Using config.

Important

It’s absolutely necessary to use the with statement to manage the trace session!

Example:

with act.trace(db_events=['log_connections = true']):
    # Actions that would be traced
    act.execute()
# Actions that are not traced

trace_to_stdout(*, upper=False)¶

Copy trace session log to .stdout.

Parameters:: upper (bool) – Convert trace log to uppercase.
Return type:: None

property bin_dir: Path¶: Path to directory with Firebird utilities.

property clean_expected_stderr: str¶: Content of expected_stderr passed through .clean_string() [R/O].

Important

Value is cached once evaluated. Use .reset() before new .expected_stderr value is assigned to force re-evaluation.

property clean_expected_stdout: str¶: Content of expected_stdout passed through .clean_string() [R/O].

Important

Value is cached once evaluated. Use .reset() before new .expected_stdout value is assigned to force re-evaluation.

property clean_stderr: str¶: Content of stderr passed through .clean_string() [R/O].

Important

Value is cached once evaluated. Use .reset() before new .stderr value is assigned to force re-evaluation.

property clean_stdout: str¶: Content of stdout passed through .clean_string() [R/O].

Important

Value is cached once evaluated. Use .reset() before new .stdout value is assigned to force re-evaluation.

db: Database¶: Primary test database.

expected_stderr: str¶: Expected error output.

expected_stdout: str¶: Expected standard output.

property files_dir: Path¶: Path to directory with test suite data files.

property home_dir: Path¶: Path to Firebird home directory.

property host: str¶: Host machine of tested Firebird server.

outfile: Path¶: Base path/filename for stdout/stderr protocols of external Firebird tool execution.

property platform: str¶: Current execution platform identifier.

property port: str¶: Port of tested Firebird server.

property protocol: NetProtocol | None¶: Default protocol for connections to databases.

return_code: int¶: Return code from last execution of external Firebird tool.

property script: str¶: Test script that should be executed by ~Action.execute.

property security_db: str¶: Path to Firebird security database.

stderr: str¶: Content of error output from last execution of external Firebird tool.

stdout: str¶: Content of standard output from last execution of external Firebird tool.

substitutions: List[Tuple[str, str]]¶: REGEX substitutions applied on stdout/stderr on cleanup.

trace_log: List[str]¶: Output from last executed trace session.

property vars: Dict[str]¶: Dictionary with various configuration parameters and variables used by plugin.

ExecutionError¶

class firebird.qa.plugin.ExecutionError¶

Bases: Exception

Exception used to indicate errors when external QA tools (like isql, gstat etc.) are executed.

pytest hooks¶

pytest_addoption¶

firebird.qa.plugin.pytest_addoption(parser, pluginmanager)¶: Adds plugin-specific pytest command-line options.

See also

pytest documentation <_pytest.hookspec.pytest_addoption> for details.

pytest_report_header¶

firebird.qa.plugin.pytest_report_header(config)¶: Returns plugin-specific test session header.

See also

pytest documentation <_pytest.hookspec.pytest_report_header> for details.

pytest_configure¶

firebird.qa.plugin.pytest_configure(config)¶

Plugin configuration.

Whta it does:

define version, platform and slow markers.
sets values for our globals (accessible as Action.vars)
if server section in driver-config contains client library specification, it’s copied to global driver config.
installs our QATerminalReporter

See also

pytest documentation <_pytest.hookspec.pytest_configure> for details.

pytest_collection_modifyitems¶

firebird.qa.plugin.pytest_collection_modifyitems(session, config, items)¶

Post-processing of collected tests. deselects or mark for skip tests that are not intended for currently tested Firebird version or platform.

Also parses doctring from test function or module to extract our metadata, and sets them as _qa_* attributes on Item <_pytest.nodes.Item> instance.

See also

pytest documentation <_pytest.hookspec.pytest_collection_modifyitems> for details.

pytest_runtest_makereport¶

firebird.qa.plugin.pytest_runtest_makereport(item, call)¶

Our replacement for pytest hook that is called to create a TestReport for each of the setup, call and teardown runtest phases of a test item.

Our version makes a copy of all _qa_* attributes from item to returned report instance.

See also

pytest documentation <_pytest.hookspec.pytest_runtest_makereport> for details.

Internal functions¶

log_session_context¶

firebird.qa.plugin.log_session_context(record_testsuite_property)¶: Autoused session fixture that records version,`architecture` and mode XML propeties.

set_tool¶

firebird.qa.plugin.set_tool(tool)¶: Helper function for pytest_configure.

substitute_macros¶

firebird.qa.plugin.substitute_macros(text, macros)¶: Helper function to substitute $(name) macros in text.

Important

Used only for backward compatibility with fbtest. The use of $(name) macros in tests is deprecated.

db_path¶

firebird.qa.plugin.db_path(tmp_path)¶

Internal fixture function that returns path to temporary directory for database files.

On non-Windows platforms makes sure that directory has permissions that user, group and other can write there. :rtype: Path

See also

tmp_path <_pytest.tmpdir.tmp_path> fixture.

trace_thread¶

firebird.qa.plugin.trace_thread(act, b, cfg, output, keep_log, encoding, encoding_errors, user, password, role, stop)¶

Function used by TraceSession for execution in separate thread to run trace session.

Parameters:

act (Action) – Action instance.
b (Barrier) – Barrier instance used for synchronization.
cfg (List[str]) – Trace configuration.
output (List[str]) – List used to store trace session output.
keep_log (bool) – When True, the trace session output is discarded.
encoding (str) – Encoding for trace session output.
encoding_errors (str) – Error handler for trace session output encoding.
user (str) – user name
password (str) – User password
role (str) – User role
stop (Event) – Event used to stop the trace thread

Internal classes¶

TraceSession¶

class firebird.qa.plugin.TraceSession(act, config, user, password, role=None, keep_log=True, encoding=None, encoding_errors=None)¶

Bases: object

Object to manage Firebird trace session.

Parameters:

act (Action) – Action instance.
config (List[str]) – Trace session configuration.
keep_log (bool) – When False, the trace session output is discarded.
encoding (Optional[str]) – Encoding for trace session output.
encoding_errors (Optional[str]) – Error handler for trace session output encoding.

Important

Do not create instances of this class directly! Always use Action.trace method and the with statement.

Example:

with act.trace(db_events=trace_cfg):
    # your test here
# Process trace output, for example by passing to stdout
act_1.trace_to_stdout()

The trace session is automatically stopped on exit from with context, and trace output is copied to Action.trace_log attribute.

act: Action¶: Action instance.

config: List[str]¶: Trace session configuration.

encoding: Optional[str]¶: Encoding for trace session output.

encoding_errors: Optional[str]¶: Encoding errors handling for trace session output.

keep_log: bool¶: When True, the trace session output is discarded.

output: List[str]¶: List used to store trace session output.

password: str¶: User password

role: str¶: User role

trace_thread: Thread¶: Thread used to execute trace session

user: str¶: User name

QATerminalReporter¶

class firebird.qa.plugin.QATerminalReporter(config, file=None)¶

Bases: TerminalReporter

Custom TerminalReporter that prints our QA test IDs instead pytest node IDs.

The code was directly taken from pytest source and adapted to our needs.

pytest_runtest_logreport(report)¶

Return type:: None

pytest_runtest_logstart(nodeid, location)¶

Return type:: None