Skip to content

Testing

Overview

Coldtivate uses Django's test runner for the Base API, Python test runners for the reporting services, and Maestro for mobile end-to-end testing. The automated merge-request suite currently runs on Android. Together these tests cover backend behavior and complete mobile workflows as part of the Automated QA strategy.

This page summarizes the backend and mobile test strategies. For the complete Android E2E setup, execution, reset, and troubleshooting workflow, see Mobile E2E Testing.

Backend Tests

Every backend merge request runs four blocking jobs: Base API, App Impact Reporting (AIR), Impact Dashboard, and Farmers Dashboard. See the backend CI/CD guide for pipeline triggers, result reporting, and database bootstrap details.

Base API Django tests

The Base API test environment uses Python 3.12 and Django's test runner. From backend-monorepo/Base-API, run:

pipenv install --dev --deploy
pipenv run python -Wa manage.py test base -v 2

From the repository root with Docker Compose, run:

docker-compose run web pipenv run python -Wa manage.py test base -v 2

The test runner creates and destroys its own test_<DB_NAME> database. Tests must create ORM data in setUpTestData, setUp, or the test itself; test modules and constructors must not query the database during discovery.

Live integration-test gating

Most tests are hermetic and run without external credentials. Tests that call real sensor-provider APIs are opt-in and print their status in an integration-gating banner at the start of the run.

Group Enable variable Credential variables Current status
Figorr TEST_SENSORS_FIGORR TEST_SENSORS_FIGORR_USERNAME, TEST_SENSORS_FIGORR_PASSWORD, TEST_SENSORS_FIGORR_SOURCE_ID Available when configured
Victron TEST_SENSORS_VICTRON TEST_SENSORS_VICTRON_USERNAME, TEST_SENSORS_VICTRON_PASSWORD, TEST_SENSORS_VICTRON_SOURCE_ID Available when configured
Ecozen TEST_SENSORS_ECOZEN TEST_SENSORS_ECOZEN_USERNAME, TEST_SENSORS_ECOZEN_PASSWORD, TEST_SENSORS_ECOZEN_SOURCE_ID Disabled in code
Ubibot TEST_SENSORS_UBIBOT TEST_SENSORS_UBIBOT_USERNAME, TEST_SENSORS_UBIBOT_PASSWORD, TEST_SENSORS_UBIBOT_SOURCE_ID Disabled in code

Any non-empty enable-variable value activates an available group, including strings such as 0 or false. Leave the variable unset to keep the group disabled. Never commit live provider credentials or expose them to untrusted pipelines.

The Paystack tests currently in the suite are hermetic and must run normally. TEST_PAYSTACK_LIVE is reserved for future tests that actually call Paystack's API.

Reporting-service tests

Run each reporting suite from its service directory:

# backend-monorepo/App-Impact-Reporting
pip install -r requirements-dev.txt
python -m unittest discover -s tests -v

# backend-monorepo/Impact-Dashboard-Backend
pip install -r requirements-dev.txt
python -m pytest tests/ -v

# backend-monorepo/Farmers-Dashboard-Backend
pip install -r requirements-dev.txt
python -m unittest discover -s tests -v

The requirements-dev.txt files include each service's normal requirements.txt plus its CI test-reporting dependency. Keep test-only packages out of the production requirements files.

Database-backed tests require a disposable PostGIS database containing the Base API migrations and the reporting tables/views used by the relevant service. Start the normal local development deployment to create the Base API schema and common reporting views:

./scripts/environment-deployment-management.sh deploy

Some reporting suites require additional service-specific tables or views. Apply the same SQL files listed for that service's test job in the backend .gitlab-ci.yml to the disposable local database before running those database-backed tests. The CI bootstrap performs this step automatically.

By default, the tests connect to localhost:54321 with database, username, and password set to base. Override DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, and DB_PASSWORD when using a different disposable database. Never point these suites at staging or production; some test classes create, update, or truncate fixtures. The row-count safety guards are defense in depth, not authorization to use a shared environment.

If PostGIS is unavailable locally, database-backed classes call connect_or_skip() and skip while mocked/unit tests continue. CI forces REQUIRE_TEST_DB=true at runtime, turning the same connection failure into a hard failure so a missing service cannot produce a false-green pipeline. CI also ignores inherited DB_*/DATABASE_URL targets, forces the postgis service alias, and creates a marked ci_test_<CI_JOB_ID> database. Suite-defined safety gates still apply; for example, the Farmers slicer class requires the explicit RUN_DESTRUCTIVE_FARMER_SLICER_TESTS=1 opt-in.

Backend test troubleshooting

  • If a job times out waiting for PostGIS, inspect the service-container logs. CI forces the postgis:5432 target after the service becomes ready; inherited project/group database variables are not accepted as test targets.
  • Reporting jobs need GDAL system libraries because their database bootstrap runs Base API migrations and imports its GeoDjango models.
  • Reporting services continue to run their own tests on Python 3.9. Their CI bootstrap installs a job-local Python 3.12 runtime for Base API dependencies and migrations.
  • If pipenv install --dev --deploy reports a lock mismatch, regenerate and commit Base-API/Pipfile.lock; do not remove --deploy from CI.
  • If a database-backed class skips unexpectedly in CI, confirm REQUIRE_TEST_DB=true reaches the test process and that it uses the shared tests/db_config.py helper.

Mobile Testing Framework: Maestro

Maestro is used to run end-to-end tests across Coldtivate's Android and iOS builds. The tests are defined in YAML files that outline the different flows within the application. These flows are executed through Maestro's command-line interface.

Folder Structure

All test flows are organized under the .maestro folder located in the root of the project. Here's a breakdown of the folder structure:

.maestro
├── auth
├── management
├── common
│   ├── subflows
│   └── utils
└── scripts
  • auth: contains test flows related to authentication, such as sign-up, log-in, and password reset.
  • management: includes tests for app management features such as company details, cooling units, and account invitations.
  • common:
    • subflows: reusable test steps that can be included in other flows.
    • utils: utility files for testing (e.g., test suite teardown, app launch arguments).
  • scripts: contains any helper scripts that automate test executions or support the testing infrastructure.

Test Execution

Use the repository runner for the complete ordered suite:

BASE_API_BASE_URL=http://localhost:8080/base_api .maestro/run-all.sh

The explicit flow list prevents older Maestro versions from silently discovering zero nested flows. A single flow can still be passed directly to maestro test. Follow Mobile E2E Testing to prepare the backend, build and install the Android APK, reset test data, and collect diagnostic output.

Using Maestro Studio

Maestro Studio is a powerful GUI tool that simplifies test flow creation and maintenance. Instead of writing test flows directly in YAML, you can:

  1. Record test flows by interacting with your app directly.
  2. Edit recorded flows through the visual interface.
  3. Export flows as YAML files for version control.

To launch Maestro Studio, use: 

maestro studio
Maestro Studio provides a user-friendly visual editor for test flows. You can create and modify tests by clicking through the interface without writing code, making it accessible for new users while helping all team members work more efficiently.

Best Practices

  1. Modularize tests: use the common/subflows and common/utils directories to store reusable steps or helper functions to avoid duplicating logic.
  2. Use descriptive names: give each test flow a clear and concise name that describes its purpose.
  3. Validate supported platforms: the merge-request E2E job currently validates Android. Check shared flow changes on any additional platform before adding that platform to CI.
  4. Version control: since this is an open-source project, make sure to regularly commit test flow changes to the repository for version tracking and collaboration.

Contributing

We welcome contributions to the end-to-end testing suite. To contribute, please fork the repository and follow these steps:

  1. Add your test flow to the appropriate folder (e.g., auth, management).
  2. Ensure that your flow is clearly named and contains proper assertions.
  3. Submit a pull request with a description of your changes and the tests you've added.

Test Coverage Status

Password Recovery Flows

Flow Name Status
Request password recovery ❌ Missing
Reset password ❌ Missing

Registered Employee (RE) Flows

Flow Name Status
RE sign up ✅ Added
RE sign in ✅ Added
RE add new location ✅ Added
RE invite operator ✅ Added
RE add new cooling unit ✅ Added
RE Seller Settings - add payout options ❌ Missing
RE Seller Settings - add discount coupons ❌ Missing
RE Management - update company details ❌ Missing
RE Management - invite registered employee ❌ Missing
RE Management - add company payout options ❌ Missing
RE Management - add company delivery contacts ❌ Missing
RE Management - add company discount coupons ❌ Missing
RE Marketplace - buy crate for himself ❌ Missing
RE Marketplace - buy crate on behalf of company ❌ Missing
RE History - check marketplace movement ❌ Missing

Operator (OP) Flows

Flow Name Status
OP login ✅ Added
OP check in produces ✅ Added
OP check out produces ✅ Added
OP Seller Settings - update contact sharing settings ❌ Missing
OP Management - invite cooling user ❌ Missing
OP Dashboard - set crate for sale ❌ Missing
OP Marketplace - buy crate for himself ❌ Missing
OP Marketplace - buy crate on behalf of company ❌ Missing
OP History - check marketplace movement ❌ Missing

Cooling User (CU) Flows

Flow Name Status
Cooling user sign up ✅ Added
Cooling user sign in ✅ Added
Cooling user Details - update personal details ❌ Missing
Cooling user Details - update localization preferences ❌ Missing
Cooling user Details - fill in a cooling user survey ❌ Missing
Cooling user Seller Settings - revoke discount coupons ❌ Missing
Cooling user Dashboard - set crate for sale ❌ Missing
Cooling user Marketplace - buy crate ❌ Missing
Cooling user History - check marketplace movement ❌ Missing