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 aliasemployee
. The database with this alias must be defined indatabases.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 inbackups
directory.copy_of (
Optional
[str
]) – Filename (without path) of the database that should be copied as test database. File must be located indatabases
directory.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
) – WhenTrue
, 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
) – WhenTrue
, 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
) – WhenTrue
[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.
existing_db_factory¶
- firebird.qa.plugin.existing_db_factory(*, filename='test.fdb', charset=None, user=None, password=None, config_name='pytest', utf8filename=False)¶
Factory function that returns fixture providing the
Database
instance to existing database.- Parameters:
filename (
str
) – Test database filename. It’s also possible to specify database alias using ‘#’ as prefix, for example#employee
means aliasemployee
. The database with this alias must be defined indatabases.conf
.user (
Optional
[str
]) – User name used to connect the test database. Default is taken from server configuration.password (
Optional
[str
]) – User password used to connect the test database. Default is taken from server configuration.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 whenwith
context is entered.
Important
The
db_fixture_name
must be name of variable that holds the fixture created bydb_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:
Important
The
db_fixture_name
must be name of variable that holds the fixture created bydb_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.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 beNone
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 onlyUSER
orROLE
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
) – WhenTrue
, the mapping is not created whenwith
context is entered.
Important
The
db_fixture_name
andsource_db_fixture_name
must be names of variable that holds the fixture created bydb_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¶
temp_files¶
isql_act¶
python_act¶
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 callconnect
orcreate_database
.- Return type:
- 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:
password (
Optional
[str
]) – User password for this connection.no_gc (
Optional
[bool
]) – WhenTrue
, the Garbage Collection is disabled for this connection.no_db_triggers (
Optional
[bool
]) – WhenTrue
, the database triggers are disabled for this connection.dbkey_scope (
Optional
[DBKeyScope
]) – Scope fordb_key's
for this connection.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:
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.
Note
Typically, this method is used only by
db_factory
to create the test database (during fixture setup) unlessdo_not_create
argument is set to True.
- create(page_size=None, sql_dialect=None, cache=None)¶
Create the test database.
- Parameters:
- Return type:
Note
Typically, this method is used only by
db_factory
to create the test database (during fixture setup) unlessdo_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) unlessdo_not_drop
argument is set to True.
- get_config()¶
Returns firebird-driver configuration for test database.
- Return type:
- init(script)¶
Initialize the test database by running ISQL script.
- Parameters:
script (
str
) – SQL script content to be executed by ISQL.- Return type:
Note
Typically, this method is used only by
db_factory
to initialize the test database (during fixture setup) unlessdo_not_create
argument is set to True.
- restore(backup)¶
Create the test database from backup.
Note
Typically, this method is used only by
db_factory
to create the test database (during fixture setup) unlessdo_not_create
argument is set to True.
- 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 withfbtest
.
- 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 whenwith
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
andteardown
is managed via context manager protocol and the with statement that must be executed within scope of used database. Fixture created byuser_factory
does this automatically.- create()¶
Creates user in security context of defined test database. Called automatically when
with
context is entered anddo_not_create
isFalse
. :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.
- set_tag(name, *, value)¶
Create/Set user tag value.
Role¶
- class firebird.qa.plugin.Role(database, name, charset, do_not_create)¶
Bases:
object
Object to access and manage single Firebird test role.
- Parameters:
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
andteardown
is managed via context manager protocol and the with statement that must be executed within scope of used database. Fixture created byrole_factory
does this automatically.- create()¶
Creates role in test database. Called automatically when
with
context is entered anddo_not_create
isFalse
. :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:
- charset¶
Firebird CHARACTER SET used for connections that manage this role.
Envar¶
- class firebird.qa.plugin.Envar(name, value)¶
Bases:
object
Object to manage environment variables in tests.
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
andteardown
is managed via context manager protocol and the with statement. Fixture created byenvar_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
) – WhenTrue
, the mapping is not created whenwith
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 beNone
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 onlyUSER
orROLE
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
andteardown
is managed via context manager protocol and the with statement that must be executed within scope of used database. Fixture created bymapping_factory
does this automatically.- drop()¶
Drop role in defined test database. Called automatically on
with
context exit.- Return type:
- charset¶
Firebird CHARACTER SET used for connections that manage this mapping.
-
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.
ServerKeeper¶
- class firebird.qa.plugin.ServerKeeper(act, server)¶
Bases:
object
Helper context manager class to temporary change the server used by
Action
.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
orpython_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:
- 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].encoding (
Optional
[str
]) – Encoding for service output override.encoding_errors (
Optional
[str
]) – Error handler for service output encoding override.
- Return type:
- envar(name, value)¶
Temporary set an environment variable.
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:
By default, script is executed on primary test database with
Database
charset. ISQL output is captured intostdout
andstderr
, and exit code is stored intoreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into test protocol files without
/err
suffix.Important
If
return_code
is not zero, and script execution failure is not expected (either via definedexpected_stderr
value or usingcombine_output
= True), it raisesExecutionError
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:
By default, metadata are extracted from primary test database using
Database
charset. ISQL output is captured intostdout
andstderr
, and exit code is stored intoreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into test protocol files without
/err
suffix.Important
If
return_code
is not zero, it raisesExecutionError
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 tosubprocess.run
).io_enc (
Optional
[str
]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.credentials (
bool
) – WhenTrue
adds switches to connect as primary test database user.combine_output (
bool
) – Combine stdout/stderr into stdout.
- Return type:
By default, GBAK is executed on primary test database, and output is captured into
stdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into test protocol files without
/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 definedexpected_stderr
value or usingcombine_output
= True), it raises andExecutionError
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:
- Return type:
Database name is passed to
connect
. By default, it usesemployee
database. To get database-specific configuration values, you should always specify thedatabase
value usingDatabase.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.
- get_server_architecture()¶
Returns server architecture:
SuperServer
,Classic
,SuperClassic
orEmbedded
.- Return type:
- 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 tosubprocess.run
).io_enc (
Optional
[str
]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.credentials (
bool
) – WhenTrue
adds switches to connect as primary test database user.combine_output (
bool
) – Combine stdout/stderr into stdout.
- Return type:
By default, GFIX is executed on primary test database, and output is captured into
stdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into protocol files without
/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 definedexpected_stderr
value or usingcombine_output
= True), it raises andExecutionError
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 tosubprocess.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
) – WhenTrue
adds switches to connect as primary test database user.
- Return type:
By default, GSEC is executed on primary test database, and output is captured into
stdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into test protocol files without
/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 raisesExecutionError
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 tosubprocess.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
) – WhenTrue
adds primary test database DSN to switches.credentials (
bool
) – WhenTrue
adds switches to connect as primary test database user.
- Return type:
By default, GSTAT is executed on primary test database, and output is captured into
stdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into test protocol files without
/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 raisesExecutionError
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.
- 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 tosubprocess.run
).io_enc (
Optional
[str
]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.input_file (
Optional
[Path
]) – Path to isql input file (passed with -i switch).connect_db (
bool
) – WhenTrue
, database DSN is added to isql switches.credentials (
bool
) – WhenTrue
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:
By default, isql is executed on test database with
Database
charset, and output is captured intostdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into protocol files without
/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 definedexpected_stderr
value or usingcombine_output
= True), it raises andExecutionError
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. ReturnsTrue
is any pattern is found.
- 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 tosubprocess.run
).io_enc (
Optional
[str
]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.credentials (
bool
) – WhenTrue
adds switches to connect as primary test database user.combine_output (
bool
) – Combine stdout/stderr into stdout.
- Return type:
By default, NBACKUP is executed on primary test database, and output is captured into
stdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into protocol files without
/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 definedexpected_stderr
value or usingcombine_output
= True), it raises andExecutionError
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:
- print_data(cursor)¶
Print data from cursor in tabular format, like standard printout in ISQL.
- Return type:
- print_data_list(cursor, *, prefix='')¶
Print data from cursor in list format, like list printout in ISQL.
- Return type:
- reset()¶
Reset internal variables used to store output from execution of external tool. :rtype:
None
- strip_white(value)¶
Remove all leading and trailing whitespace characters on ALL lines in value.
- Return type:
- 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 tosubprocess.run
).io_enc (
Optional
[str
]) – Python encoding to be used to decode text output instead encoding that corresponds to used character set.connect_mngr (
bool
) – WhenTrue
, adds switches to connect service manager of tested server using credentials for primary test database.
- Return type:
By default, primary test database charset is used to determine the encoding for strings, and output is captured into
stdout
andstderr
, and exit code is stored toreturn_code
.If pytest
--save-output
command-line option is used, the content of stdout/stderr is also stored into protocol files without
/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 andExecutionError
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.keep_log (
bool
) – WhenFalse
, the trace session output is discarded. Otherwise is stored intrace_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:
Note
There are two (mutually exclusive) methods how to configure the trace session:
Using
db_events
and/orsvc_events
lists, and optionaldatabase
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
- property clean_expected_stderr: str¶
Content of
expected_stderr
passed throughclean_string()
[R/O].Important
Value is cached once evaluated. Use
reset()
before newexpected_stderr
value is assigned to force re-evaluation.
- property clean_expected_stdout: str¶
Content of
expected_stdout
passed throughclean_string()
[R/O].Important
Value is cached once evaluated. Use
reset()
before newexpected_stdout
value is assigned to force re-evaluation.
- property clean_stderr: str¶
Content of
stderr
passed throughclean_string()
[R/O].
- property clean_stdout: str¶
Content of
stdout
passed throughclean_string()
[R/O].
- property protocol: NetProtocol | None¶
Default protocol for connections to databases.
ExecutionError¶
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
andslow
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 onItem
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` andmode
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¶
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.output (
List
[str
]) – List used to store trace session output.keep_log (
bool
) – WhenTrue
, 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 namepassword (
str
) – User passwordrole (
str
) – User rolestop (
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:
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 toAction.trace_log
attribute.
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.