{"id":19923277,"url":"https://github.com/firebirdsql/firebird-qa","last_synced_at":"2025-10-14T08:34:20.617Z","repository":{"id":47308553,"uuid":"295681819","full_name":"FirebirdSQL/firebird-qa","owner":"FirebirdSQL","description":"Python tools used for Firebird QA","archived":false,"fork":false,"pushed_at":"2025-10-06T04:41:50.000Z","size":46921,"stargazers_count":3,"open_issues_count":7,"forks_count":8,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-10-06T06:36:12.439Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://firebirdsql.org/en/devel-qa/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FirebirdSQL.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":"https://firebirdsql.org/en/donate/"}},"created_at":"2020-09-15T09:41:22.000Z","updated_at":"2025-10-06T04:41:53.000Z","dependencies_parsed_at":"2024-01-22T19:27:08.296Z","dependency_job_id":"0bf6c682-035b-4c84-9d6e-9d0f17b99e66","html_url":"https://github.com/FirebirdSQL/firebird-qa","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/FirebirdSQL/firebird-qa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Ffirebird-qa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Ffirebird-qa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Ffirebird-qa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Ffirebird-qa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FirebirdSQL","download_url":"https://codeload.github.com/FirebirdSQL/firebird-qa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Ffirebird-qa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018307,"owners_count":26086342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T22:13:39.431Z","updated_at":"2025-10-14T08:34:20.568Z","avatar_url":"https://github.com/FirebirdSQL.png","language":"Python","funding_links":["https://firebirdsql.org/en/donate/"],"categories":[],"sub_categories":[],"readme":"# Firebird QA\n\nThis repository contains:\n\n- pytest plugin that provides support for testing the Firebird engine. It uses new Python\n  driver for Firebird (`firebird-driver`).\n- tests for Firebird engine (directory `tests`)\n- files needed by tests (directories `databases`, `files`, `backups` and `configs`)\n\n**Requirements:** Python 3.8+, Firebird 3+\n\nYou should definitelly read the [QA suite documentation](https://firebird-qa.readthedocs.io)!\n\n## Quickstart\n\n1. Clone the git repository\n\n2. If you don't have `pipx` tool installed, install it using::\n\n   ```\n   python -m pip install pipx\n   ```\n\n   Or you can use any other method listed at [pipx website](https://pipx.pypa.io).\n\n   \u003e Don't forget to run:\n   \u003e\n   \u003e  pipx ensurepath\n   \u003e\n   \u003e once after installation to ensure that tools installed via `pipx` will be available on\n   \u003e search path.\n\n3. Install the plugin and required dependencies by running next command:\n\n   ```\n   pipx install --include-deps firebird-qa\n   ```\n\n3. Adjust Firebird server configuration.\n\n   **ONLY FOR MANUAL runs:**\n\n   Check content of `$FB_HOME/databases.conf.`\n\n   Ensure that RemoteAccess is allowed for `security.db`.\n   Also, it is recommended to set number of buffers not less than 256 for it:\n\n   ```\n   security.db = $(dir_secDb)/security\u003csuffix\u003e.fdb\n   {\n       RemoteAccess = true\n       DefaultDbCachePages = 256\n   }\n   ```\n\n   This must be done only if you want to run some tests manually.\n   Automated scenario for running tests will overwrite this file\n   and put there all needed data before every pytest session (using\n   `$QA_ROOT/files/qa-databases.conf` as prototype for that purpose).\n\n    1. `$FB_HOME/firebird.conf`:\n\n        **Firebird 3:**\n\n        ```\n        # Required\n        BugcheckAbort = 1\n        ExternalFileAccess = Full\n        AuthServer = Srp, Win_Sspi, Legacy_Auth\n        UserManager = Srp, Legacy_UserManager\n        WireCrypt = Enabled\n        FileSystemCacheThreshold = 99999K\n        IpcName = xnet_fb3x_qa\n        RemotePipeName = wnet_fb3x_qa\n\n        # Recommended\n        DefaultDbCachePages = 10000\n        MaxUnflushedWrites = -1\n        MaxUnflushedWriteTime = -1\n\n        # Needed for encryption-related tests.\n        KeyHolderPlugin = fbSampleKeyHolder\n        ```\n\n        **Firebird 4:**\n        ```\n        # Required\n        BugcheckAbort = 1\n        ExternalFileAccess = Full\n        AuthServer = Srp, Win_Sspi, Legacy_Auth\n        UserManager = Srp, Legacy_UserManager\n        ReadConsistency = 0\n        WireCrypt = Enabled\n        ExtConnPoolSize = 10\n        ExtConnPoolLifeTime = 10\n        UseFileSystemCache = true\n        IpcName = xnet_fb4x_qa\n        RemotePipeName = wnet_fb4x_qa\n\n        # Recommended\n        DefaultDbCachePages = 10000\n        MaxUnflushedWrites = -1\n        MaxUnflushedWriteTime = -1\n\n        # number of seconds after which statement execution will be automatically cancelled\n        # by the engine\n        # can be very useful if some test will hang or become work extremely slow:\n        StatementTimeout = 7200\n\n        # Needed for encryption-related tests:\n        KeyHolderPlugin = fbSampleKeyHolder\n        ```\n\n        **Firebird 5:**\n\n        currently all parameters from FB-4.x can be used, except 'RemotePipeName'\n        because support of WNET protocol was removed from FB-5.x.\n        It is recommended to assign value like 'xnet_fb5x_qa' to IpcName.\n\n        \u003e [!NOTE]\n        \u003e Proper values of some parameters strongly depends on ServerMode and amount of\n        \u003e avaliable RAM.\n        \u003e\n        \u003e * DefaultDbCachePages::\n        \u003e   On Classic/SuperClassic it must not be greater than 4K in real systems. For tests\n        \u003e   10K...20K is OK.\n        \u003e   On Super it can be increased so that size of page cache become 25%...33% of\n        \u003e   physical RAM.\n        \u003e * TempCacheLimit::\n        \u003e   On Classic usually it must be limited because every connection uses its own memory area\n        \u003e   for sort purposes. Nowadays may to use values about 256M ... 512M.\n        \u003e   On SuperClassic and Super common memory area is used to sorts, so this parameter can have\n        \u003e   values of dozen Gb. As first approximation, it can be set up to 33% of total RAM.\n\n\n    2. Changes in OS environment variables:\n\n       it is recommended to create variable `FIREBIRD_TMP` that will point to the pre-created directory\n       on some fast drive (e.g. SSD or RAM). This drive must have at least 30 Gb free space.\n       Once this variable is defined, one may not specify parameter 'TempDirectories'.\n\n    3. Required changes for running encryption-related tests::\n\n        1. Change dir to `$FB_HOME/examples/prebuilt/plugins/` and make copy of following files into `$FB_HOME/plugins/` :\n\n            1. Configs:\n\n               ```\n               fbSampleKeyHolder.conf\n               fbSampleDbCrypt.conf\n               ```\n            2. Binaries on Windows:\n               ```\n               fbSampleDbCrypt.dll\n               fbSampleKeyHolder.dll\n               ```\n            3. Binaries on Linux:\n               ```\n               libfbSampleDbCrypt.so\n               libfbSampleKeyHolder.so\n               ```\n\n               \u003e [!NOTE]\n               \u003e These files missed in Firebird 3.x but one may to use such files from any\n               \u003e recent FB 4.x snapshot.\n               \u003e Config parameter KeyHolderPlugin currently is 'fbSampleKeyHolder'.\n               \u003e This value must match to value of parameter 'ENCRYPTION_HOLDER' that is\n               \u003e specified in the file `$(QA_ROOT)/files/test_config.ini` (it contains several settings that are common for many tests).\n\n        2. In `$FB_HOME/plugins/fbSampleKeyHolder.conf`:\n           ```\n           Auto = true\n           KeyRed=111\n           KeyGreen = 119\n           ```\n        3. In `$FB_HOME/plugins/fbSampleDbCrypt.conf`:\n           ```\n           # Encure that Auto = false or just is commented out\n           ```\n        4. Restart Firebird and check that all set correct. Example for Linux:\n           ```\n           shell rm -f /var/tmp/tmp4test.fdb;\n           create database 'localhost:/var/tmp/tmp4test.fdb' user sysdba password 'masterkey';\n           ```\n\n           **Following must PASS:**\n           ```\n           set echo on;\n           set bail on;\n           alter database encrypt with \"fbSampleDbCrypt\" key Red;\n           shell sleep 2;\n\n           alter database decrypt;\n           shell sleep 2;\n\n           alter database encrypt with \"fbSampleDbCrypt\" key Green;\n           shell sleep 2;\n\n           alter database decrypt;\n           shell sleep 2;\n\n           set echo off;\n           set bail off;\n           ```\n           **Following must FAIL with:**\n           ```\n           -- Statement failed, SQLSTATE = 42000\n           -- unsuccessful metadata update\n           -- -ALTER DATABASE failed\n           -- -Missing correct crypt key\n           -- -Plugin fbSampleKeyHolder:\n           -- -Crypt key NOSUCH not set\n\n           set echo on;\n           alter database encrypt with \"fbSampleDbCrypt\" key NoSuch;\n           shell sleep 2;\n\n           show database;\n           quit;\n           ```\n        \u003e [!IMPORTANT]\n        \u003e Ensure that EMPLOYEE database was not encrypted before with key/value that is unknown currently!\n        \u003e Otherwise attempt to run ANY test will fail with:\n        \u003e ```\n        \u003e   INTERNALERROR\u003e firebird.driver.types.DatabaseError: Missing database encryption key for your attachment\n        \u003e   INTERNALERROR\u003e -Plugin fbSampleKeyHolder:\n        \u003e   INTERNALERROR\u003e -Crypt key \u003cHERE_SOME_UNKNOWN_KEY\u003e not set\n        \u003e ```\n\n    4. Additional issues about folder `$(dir_sampleDb)` (`$FB_HOME/examples/empbuild/`) and its subdirectories.\n\n        1. There are many tests which supposes that this directory is avaliable for read/write access.\n           Test suite (firebird-qa plugin for pytest) will re-create subdirectory with name 'qa' under `$(dir_sample)` for\n           every such test, so be sure that you have not any significant data in this folder.\n        2. Firebird 4.x+ has ability to involve databases in replication schema. There are several tests which assumes that\n           such schema already was created (before pytest session) and there arte two databases in it (master and replica).\n           It was decided to use directory with name: `$(dir_sampleDb)/qa_replication/` for this purpoces. Two databases must\n           be created in it: `db_main.fdb` and `db_repl.fdb`, and one need to prepare them into replication beforehand.\n           Also, one need to prepare two directories in THIS folder which will serve as replication journal and archive.\n           All these actions are performed by batch scenarios which can be provided by IBSurgeon company by request.\n\n\n4. Optional. Enable your OS to create dump files in case of FB crashes caused by tests::\n\n    1. Windows:\n        1. Parameter `BugcheckAbort` must always be set to 1, otherwise dumps will not be created.\n        2. Run regedit, navigate to key:\n           ```\n           HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\Windows Error Reporting\\LocalDumps\\\n           ```\n           Create sub-key there with name: 'firebird.exe' (without single quotes).\n           Add following parameters in the 'firebird.exe' key:\n           ```\n           DumpCount, type = DWORD, value: not less than 5;\n           DumpFoler, type = REG_EXPAND_SZ, value = directory where you want dumps to be created;\n           DumpType, type = DWORD, value = 2\n           ```\n        3. Following setting must present in the registry to disable any pop-up window when program crashes:\n           key: `HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Windows\\Windows Error Reporting\\`\n           parameter: `'DontShowUI', type =  DWORD, value: 2`\n\n    4.2. Linux:\n        File `/etc/security/limits.conf` must have setting:\n        ```\n            *               soft    core            unlimited\n        ```\n        File `/etc/sysctl.conf` must have parameter `kernel.core_pattern` that specifies\n        directory to store dumps and pattern for dumps name, e.g.:\n        ```\n        kernel.core_pattern=/var/tmp/core.%e.%t.%p\n        ```\n\n5. Cautions.\n    1. Problems can occur on Windows if we launch two FB instances which uses the same major version ODS.\n       Currently this relates to FB-4.x and FB-5.x: each of them tries to create file 'fb13_user_mapping'\n       in `%programdata%\\firebird`. This leads to conflict and attempt to connect to any DB using latter FB instance\n       issues \"Error occurred during login, please check server firebird.log for details\" and firebird.log will have:\n       \"Database is probably already opened by another engine instance in another Windows session\".\n       BE SURE THAT YOU DID NOT LAUNCH ANOTHER FIREBIRD INSTANCE THAT USES SAME ODS AS CURRENTLY TESTING.\n    2. Be sure that directory specified by FIREBIRD_TMP variable actually exists and is accessible for 'firebird' account.\n    3. Ensure that your `firebird-driver.conf` contains 'DEFAULT' section with `encoding_errors = ignore`.\n       Otherwise outcome of some tests can be unpredictable if your OS has non-ascii system console\n\n6. Use pytest to run tests.\n\n   The plugin adds next options to pytest:\n   ```\n        Firebird server:\n            --server=SERVER       Server configuration name\n            --bin-dir=PATH        Path to directory with Firebird utilities\n            --protocol={xnet,inet,inet4,wnet}\n                                  Network protocol used for database attachments\n            --runslow             Run slow tests\n            --save-output         Save test std[out|err] output to files\n            --skip-deselected={platform,version,any}\n                                  SKIP tests instead deselection\n            --extend-xml          Extend XML JUnit report with additional information\n            --install-terminal    Use our own terminal reporter\n   ```\n   To run all tests (except slow ones) against local server use next command::\n   ```\n   pytest --server local ./tests\n   ```\n\n   \u003e [!NOTE]\n   \u003e If plugin fails to determine the directory with Firebird utilities (isql, gbak etc.),\n   \u003e use `--bin-dir` option to specify it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirebirdsql%2Ffirebird-qa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirebirdsql%2Ffirebird-qa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirebirdsql%2Ffirebird-qa/lists"}