Skip to content

Testing

Overview

Coldtivate uses Django's test runner for the Base API and Maestro for end-to-end testing on Android and iOS. Together they cover backend behavior and complete mobile workflows as part of the Automated QA strategy.

This document outlines the mobile end-to-end and backend Django test strategies, including execution commands and external-integration safeguards.

Backend Django Tests

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

pipenv run python manage.py test base -v 2

From the repository root with Docker Compose, run:

docker-compose run web pipenv run python 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.

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 like comapny details, cooling units or 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

To run all the tests defined in .maestro, use the following command: 

maestro test .maestro
This command will execute all the test flows across both Android and/or iOS devices, ensuring the application behaves correctly in different environments.

Running a Specific Test Flow

To run a specific test flow, navigate to the appropriate YAML file and execute the following command: 

maestro test .maestro/auth/re-sign-up.yml
This will run the re-sign-up test flow from the auth folder.

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. Test on both platforms: always ensure that your test flows are compatible with both Android and iOS to guarantee cross-platform stability.
  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