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 (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 connect or 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 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:
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 Server instance connected to service manager of tested server.

Parameters:

  • user (Union[str, User, None]) – User name [Default taken from server configuration].

  • password (Optional[str]) – User password [Default taken from server configuration].

  • role (Union[str, Role, None]) – 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 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 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:
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:

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

  2. 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 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 for details.

pytest_report_header

firebird.qa.plugin.pytest_report_header(config)

Returns plugin-specific test session header.

See also

pytest documentation 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 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 instance.

See also

pytest documentation 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 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 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, install_terminals, start_time_info)

Bases: TerminalReporter

Custom TerminalReporter Prints tests start time if ‘–start-time’ option is specified. Prints our QA test IDs instead pytest node IDs if ‘–install-terminal’ option is specified.

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

write_ensure_prefix(prefix, extra='', **kwargs)
Return type:

None

write_fspath_result(nodeid, res, **markup)
Return type:

None