Developer Guide: Environment Setup and Daily Workflow¶

Welcome! This guide provides everything you need to set up your environment, write and run tests, and contribute to the accounting service QA framework.

Table of Contents¶

1. Getting Started
Prerequisites
Initial Environment Setup
IDE Setup
Running Your First Test
2. Daily Development Workflow
Morning Routine
Starting New Work
Committing and Pushing Code
Code Review Process
3. Writing and Running Tests
Writing a New Test
Running Tests
Debugging Tests
4. Framework In-Depth
Test Users and Roles
Test Data Configuration
Platform-Specific Details (Helios)
5. Reference
Common Tasks
Troubleshooting
Best Practices

1. Getting Started¶

Prerequisites¶

Core Tools:

Python: 3.12+
uv: The project's package manager.
Git: For version control.
Docker: (Optional) For containerized setup.

Initial Environment Setup¶

Install System Dependencies: Before setting up the Python environment, ensure you have the necessary system libraries installed.
```
sudo apt install -y libmariadb3 libmariadb-dev
sudo apt-get install python3.13-dev
```

Clone the Repository:

git clone git@gitlab.fftrader.cz:fftrader/accounting-service-team/accounting-service.git
cd accounting-service/qa

Configure GitLab Authentication for uv: Store your GitLab credentials for uv to access private packages. For security, pipe your token via stdin.
```
read -sp "Enter token: " TOKEN && echo "$TOKEN" | uv auth login gitlab.fftrader.cz --username "<token-name>" --password - && unset TOKEN
```
To verify your stored credentials, run:
```
uv auth token gitlab.fftrader.cz --username <token-name>
```
> Tip: For encrypted storage using your system's native keychain, set UV_PREVIEW_FEATURES=native-auth before running uv auth login. See the uv auth CLI documentation for more details.
Install Dependencies: The project uses uv for fast and reliable dependency management.
```
# This command creates a virtual environment and installs all packages
uv sync
```
Configure Environment Variables: Copy the example .env file and add your credentials.
```
cp .env.example .env
nano .env  # Or your preferred editor
```
You'll need to fill in BASE_URL, KEYCLOAK_BASE_URL, and user credentials.

IDE Setup¶

PyCharm (Recommended)¶

Open Project: Open the accounting-service/qa directory.
Configure Interpreter:
Go to Settings > Project > Python Interpreter.
Click the gear icon, select Add..., and choose the virtual environment located in the .venv directory or create new .
Configure Test Runner:
Go to Run > Edit Configurations....
Add a new "Behave" configuration, pointing the script path to the features directory.

IntelliJ Idea Ultimate¶

Open Project: Open the accounting-service/qa directory.
Configure Interpreter:
Go to Settings > Project Structure > Platform Settings/SDKs.
Click the + icon, select Add Python SDK rom disk, and choose the virtual environment located in the .venv directory or generate new uv virtual environment.
Configure Test Runner:
Go to Run > Edit Configurations....
Edit "Behave" configuration template > set Working directory to .../accounting-service/qa and use SDK module accounting-service as Python Interpreter
If you do not see "Behave", install these plugins: Python, Python Community Edition, Gherkin, PythonDAP (https://youtrack.jetbrains.com/projects/PY/issues/PY-87004/Python-Behave-Run-Configurations-Showing-as-Unknown-After-IntelliJ-IDEA-2025.3-Upgrade)

VSCode¶

Open Project: Open the accounting-service/qa directory.
Install Extensions: Python (Microsoft), Pylance, and Cucumber (Gherkin) Full Support.
Select Interpreter: Use Ctrl+Shift+P and select the Python interpreter located in the .venv directory.

Running Your First Test¶

Run a quick "regression test" to ensure everything is set up correctly.

# From the qa/ directory
uv run behave --tags=@regression

You should see a series of tests pass successfully. If not, refer to the Troubleshooting section.

2. Daily Development Workflow¶

Morning Routine¶

Pull Latest Changes:
```
git checkout main
git pull origin main
```

Update Dependencies:

uv sync # Ensures your environment matches the lock file

Run Regression Tests:
```
uv run behave --tags=@regression
```

Starting New Work¶

Create a descriptive feature branch from main.

# For a new feature
git checkout -b feature/FSY-1234-add-crypto-validation

# For a bug fix
git checkout -b fix/FSY-1234-fix-vat-calculation

Committing and Pushing Code¶

Commit frequently with clear, conventional messages (e.g., feat(qa): ... [FSY-1234], fix(qa): ...[FSY-1234]).
Push your branch to the remote repository.
Create a Merge Request in GitLab with a descriptive title and summary of changes.

Code Review Process¶

As an author: Respond to feedback promptly and push changes to the same branch.
As a reviewer: Check for code quality, test coverage, and adherence to best practices.

3. Writing and Running Tests¶

Warning Only one document can be imported into one specific DB at a time. If that happens, a MUTEX_ERROR is thrown.

Purpose of these tests:¶

Validation of correct data in generated documents: This includes document info, supplier/customer info, and price with VAT.
Validation of the appropriate level of access for users: This ensures that customers can only access their own documents and users are restricted to the GDPR group they are part of.

Writing a New Test¶

Tests are written in Gherkin syntax (.feature files) and implemented in Python step definitions.

Example Feature File (features/ftmo_eval_global.feature):

@regression
Scenario: Import a simple Challenge invoice
Given I use "CLIENT_NBO" "service" token for document import
And I use "CZ" "user" token for accessing data
When I POST document data for "CZ" with these parameters
| Database    | Invoice Type | Currency | Price |
| EVAL_GLOBAL | CHALLENGE    | USD      | 100   |
Then I verify that the response status code is: "201"

Example Step Definition (steps/document_steps.py):

@when('I POST document data for "{user_id}" with these parameters')
def post_document_data_step(context: Context, user_id: str):
  """Posts document import data for the specified user."""
  context.import_config = ImportConfig(table_row_to_dict(context.table))
  controller = context.controller[context.import_user, context.import_client]
  _import_document_with_retry(context, controller, user_id)

Running Tests¶

Run all tests: uv run behave
Run a specific feature: uv run behave features/access_test.feature
Run tests with a specific tag: uv run behave --tags=@regression
Stop on the first failure: uv run behave --stop

Debugging Tests¶

Use print() statements: Run with behave --no-capture to see the output.
Use the logger: Add steps_logger.debug(...) and set LOG_LEVEL=DEBUG in your .env file.
Use a debugger:
In PyCharm, set a breakpoint and right-click the test to debug.
Manually, add import pdb; pdb.set_trace() in your code to start an interactive debugging session.

4. Framework In-Depth¶

Test Users and Roles¶

Tests are divided so that one feature file tests access for one user or client. The framework uses a set of pre-configured test users with different roles and permissions to validate access control.

ACCOUNTING_ADMIN: Full access to all DBs and everyone's documents, can import new document data.
Roles: accounting, accounting_editor
GDPR Groups: Member of all groups (ftmo_eval_global, jv_prop_eval_us, ftmo_trading_global, oanda_prop_trading_us, vrgk)
ACCOUNTING_READ_ONLY: Read-only access to all DBs and documents; cannot import new data.
Roles: accounting
GDPR Groups: Member of all groups.
FTMO_EVAL_GLOBAL: Limited to ftmo_eval_global DB and own documents.
JV_PROP_EVAL_US: Limited to jv_prop_eval_us DB and own documents (replaces former FTMO_EVAL_US).
FTMO_TRADING_GLOBAL: Limited to ftmo_trading_global DB and own documents.
OANDA_PROP_TRADING_US: Limited to oanda_prop_trading_us DB and own documents (replaces former FTMO_TRADING_US).
VRGK: Limited to vrgk DB and own documents.
CLIENT_NBO: KeyCloak client. A service token for backend operations like document generation and organization import.

Test Data Configuration¶

Test Users: Defined in test_data/test_users.dev.yaml.
Payment Info: JSON files located in test_data/, such as payment_info_challenge.json.
Enums: Core configurations like database settings, currencies, and item types are managed in the enums/ directory.

Helios Specific Details¶

Helios is the primary Czech accounting software system used. Some variables, such as specific Helios database settings and user IDs, are automatically filled during test runs.

Database Configuration: The DB name in tests specifies the Helios DB and its associated accounting settings. These are defined in enums.enums_db_setting.DatabaseSetting. This enum also contains constants for FTMO companies assigned to a specific DB, which are then filled into the document.
Error Handling: When importing data, Helios often does not return a specific error message for invalid cases. Instead, it may return a JSON object of all keys that can be imported.

"TiskoveId" Import Argument¶

This string argument (0-9, A-Z) contains specific information about document formatting. Currently, the first two characters are used (out of a maximum length of 25). The 3rd character, previously used for proforma documents, is deprecated.

1st Character (Footer Text): Controls the legal text displayed in the document footer. The specification is maintained in "Invoice country specific requirements 2025". The logic for selecting the footer is in helpers.document_helper.get_bank_info.
2nd Character (Payment Information): Controls the display of payment information, behaving differently for invoices and payouts. This data is supplied via the Metadata key.
- Invoices (for rewards or FTMO Points transfers):
  - 0: No text is displayed.
  - 1: "An amount of {payment-info-payment} will be paid to the customer. Rest of the invoice amount will be credited to {payment-info-company-id} for purchasing new Challenge(s) for the client."
  - 2: "An amount of {payment-info-payment} will be paid to the customer. The remaining balance of the invoice amount will be transferred to FTMO Points, which expire three years from the date of purchase."
  Metadata Example (Invoice):
```
{
  "payment-info-payment": "350",
  "payment-info-company-id": "5"
}
```
- Payouts:
  - 0: No payment information is displayed.
  - 1: Displays the full payment information block.
  Metadata Example (Payout/Reward):
```
{
  "Amount to pay": "155 EUR",
  "Account Holder Name": "Pišta Hufnágl",
  "Recipient type": "Imaginary Person",
  "ACH routing number": "077704411",
  "Account number": "223016111111",
  "Account type": "Checking",
  "Country": "Czech Republic",
  "City": "Olomouc",
  "Recipient Address": "Malá 187",
  "ZIP Code": "32832"
}
```
  Note: These metadata values are deleted after use, but only if the 2nd character of TiskoveId is set to 1.

"PoBox" Import Argument¶

This field is used to define a state code. The framework will then display the full name of the state on the invoice. If the country has no defined states (see enums.py) or the value is not a known state code, the string is passed as-is.

Local Tax Registration¶

The framework applies zero-rated VAT (0%) by default. If a jurisdiction has a local tax registration, the specific VAT rate is applied. - Test Data Setup: enums.enums_company.Company - Finance Configuration: "Tax registrations by country" document.

Credit Note Document ID¶

For Reward credit notes, if the DodFakKV argument is not empty, its value is used as the document ID in the header instead of the standard DodFak.

Supplier Bank Account Info¶

The supplier bank account is chosen based on the company (derived from the selected DB) and the currency (Mena) used in the document import. - Configuration: enums.enums_bank_account.BankAccount - Implementation: helpers.document_helper.get_bank_info

"CisloUcetPol" Import Argument¶

This argument defines the accounting account number for invoice items, determining which general ledger account the item affects in Helios. - Configuration: enums.enums_item_types.CisloUcetPol - Specification: "Helios - čísla účetních účtů" document.

5. Reference¶

Common Tasks¶

Update dependencies: uv sync
Check code style: ruff check .
Format code: ruff format .

Troubleshooting¶

ModuleNotFoundError: Your virtual environment is likely out of sync. Run uv sync.
401 Unauthorized: Check your credentials in the .env file.
409 Conflict: This is usually handled by the framework's retry logic. If it persists, check the timestamp generation.
Connection Timeouts: Verify the BASE_URL in your .env file and your network connection.

Best Practices¶

Keep scenarios independent.
Use descriptive names for tests and variables.
Extract common logic into helper functions.
Commit frequently with clear, conventional messages.
For a deeper dive into the framework's design, refer to the Architecture.

Document Version: 1.0 Last Updated: February 4, 2026 Maintained By: FinSys team