Testing and validation are required before an INTERA Integration Module is used in a customer environment or prepared for future publication in the INTERA Online Store.
An integration should not only work when the external system is available and returns perfect data. It should also behave predictably when credentials are wrong, data is missing, responses are slow, files are malformed, or synchronization returns unexpected results.
The purpose of testing is to confirm that INTERA can:
- load the Integration Module;
- read the manifest;
- create and configure an Integration Instance;
- call DataSources successfully;
- run synchronization safely, where supported;
- receive structured and predictable data;
- validate Metrics against expected values;
- report errors clearly;
- handle repeated execution without duplicates or inconsistent results.A good integration should be easy to test, easy to debug, and safe to run repeatedly.
Local development #
Local development is the first stage of integration testing.
During local development, the developer should run the integration in a controlled INTERA developer or trial environment before connecting it to any production system.
A typical local development setup includes:
- INTERA developer runtime or trial environment;
- local integration folder;
- test configuration values;
- test credentials or mock credentials;
- sample external system data;
- access to backend logs;
- ability to restart INTERA Core;
- ability to manually call DataSources or run sync.The first local test should confirm that INTERA can discover and load the integration.
Basic local test checklist:
1. Place the Integration Module in the expected integrations directory.
2. Start or restart INTERA Core.
3. Confirm that the integration appears in the integration catalog.
4. Confirm that the manifest fields are read correctly.
5. Create an Integration Instance.
6. Save configuration parameters.
7. Call a simple DataSource.
8. Check the returned response.
9. Review logs for warnings or errors.For the first test, it is acceptable to return mock data from a DataSource. This confirms that the integration contract works before external system complexity is added.
Example first DataSource response:
{
"status": "ok",
"source": "my_first_integration",
"generatedAt": "2026-07-17T10:30:00Z",
"summary": {
"activeCustomers": 128,
"openTickets": 7,
"overdueInvoices": 3
}
}After the mock DataSource works, the developer can replace the mock response with a real API call, SQL query, file parser, or external data request.
Local development should focus on quick feedback. Every change should be tested with a small, predictable request before larger datasets or sync processes are introduced.
Test datasets #
Every integration should include or reference test datasets.
A test dataset is a controlled set of data used to prove that the integration behaves correctly. It allows the developer, INTERA team, and future reviewers to understand what the integration is expected to return.
Test datasets may come from:
- mock data created by the developer;
- sample API responses;
- anonymized customer exports;
- sample CSV or Excel files;
- test database views;
- staging system data;
- generated synthetic records.A good test dataset should include both normal and edge-case records.
For example, a billing integration test dataset should not only include clean paid invoices. It should also include overdue invoices, cancelled invoices, missing payment dates, different currencies, inactive customers, and empty results.
Recommended test cases for a billing dataset:
- active customer;
- inactive customer;
- customer with no invoices;
- customer with paid invoices;
- customer with overdue invoices;
- invoice with missing due date;
- invoice in different currency;
- cancelled invoice;
- payment without matching invoice;
- duplicate external record;
- very large invoice amount;
- zero-value invoice.A good test dataset helps validate:
- field mapping;
- date parsing;
- currency handling;
- status normalization;
- Metric calculation;
- Asset Mapping;
- duplicate handling;
- error reporting;
- empty responses.Test data should not contain real customer secrets, personal data, passwords, private keys, production API tokens, or confidential business information unless the environment is explicitly approved for that purpose.
If anonymized customer data is used, identifiers should remain stable enough to test mapping and repeated sync behavior.
Dry-run sync #
Dry-run sync is a safe synchronization mode used to test what would happen during sync without permanently changing INTERA data.
When dry-run mode is available, developers should use it before enabling real synchronization.
A dry-run sync should answer questions such as:
- Can the integration connect to the external system?
- How many records would be imported?
- Which records would be created?
- Which records would be updated?
- Which records would be marked inactive?
- Which records would be skipped?
- Which errors or warnings would occur?A dry-run result may look like this:
{
"mode": "dry_run",
"entityType": "customer",
"summary": {
"received": 1250,
"wouldCreate": 43,
"wouldUpdate": 1189,
"wouldMarkInactive": 18,
"wouldSkip": 0
},
"warnings": []
}Dry-run sync is especially important for integrations that import business entities such as:
- customers;
- vessels;
- products;
- services;
- suppliers;
- contracts;
- trucks;
- employees;
- devices;
- sites.Dry-run mode should not create duplicate Assets, overwrite existing data, remove mappings, or trigger external actions.
If dry-run mode is not available, the developer should use a dedicated test environment and a small dataset before testing larger synchronization jobs.
A good dry-run implementation should include:
- record counts;
- planned create/update/inactive actions;
- skipped records;
- validation warnings;
- sample affected records;
- clear indication that no permanent changes were made.Dry-run sync helps developers and administrators build confidence before running real synchronization.
Error simulation #
An integration must be tested against failure cases.
External systems are not always available, fast, consistent, or correctly configured. Good error simulation helps confirm that the Integration Module fails safely and reports useful messages.
Developers should simulate common error cases during testing.
Recommended error simulation cases:
- missing required configuration;
- invalid API key;
- expired token;
- wrong username or password;
- unreachable API URL;
- DNS failure;
- connection timeout;
- external API rate limit;
- external API 500 error;
- empty response;
- malformed JSON response;
- missing CSV file;
- invalid CSV headers;
- invalid date format;
- database connection failure;
- SQL permission error;
- unsupported parameter;
- response larger than expected.Each simulated error should produce a clear operational message.
Good error message:
Cannot load invoices from Example Billing. The external API returned 401 Unauthorized. Check the API key for this Integration Instance.Poor error message:
Error.Error messages should help the administrator understand:
- what failed;
- which external system or DataSource was involved;
- whether the issue is configuration, authentication, network, data, or system related;
- whether the issue is temporary or requires administrator action.Errors must not expose secrets.
Never include these values in logs or error messages:
- API keys;
- passwords;
- bearer tokens;
- refresh tokens;
- client secrets;
- private keys;
- full database connection strings containing credentials.For sync operations, errors should distinguish between complete failure and partial success.
Example:
Customer sync completed with warnings. 1,238 records were imported, 14 records were skipped because they did not contain a stable customer ID.This is more useful than simply marking the whole sync as failed when most records were processed successfully.
Metric validation #
Metric validation confirms that values produced by the integration are correct, consistent, and meaningful inside INTERA.
A Metric is not just a number. It may have an Asset, type, time context, source, timestamp, status, threshold, and role-specific display name. For this reason, Metric validation should check both the value and its surrounding context.
A Metric validation test should confirm:
- the Metric value is correct;
- the data type is correct;
- the currency or unit is correct;
- the time period is explicit;
- the Asset relationship is correct;
- the source DataSource is known;
- the latest update timestamp is present;
- missing or delayed data is handled correctly;
- thresholds are applied correctly, where relevant;
- repeated calculation gives the same result for the same input.Example Metric validation:
{
"metric": "monthly_revenue",
"asset": "customer:CUST-1001",
"period": {
"type": "billing_month",
"value": "2026-06"
},
"value": 12500,
"currency": "EUR",
"source": "example_billing.invoices",
"generatedAt": "2026-07-17T10:30:00Z"
}The developer should be able to explain exactly how the Metric was calculated.
For example:
Metric: monthly_revenue
Calculation: sum of invoice line totals for invoices issued during the selected billing period, excluding cancelled invoices and credit notes.Metric validation should include edge cases.
Recommended Metric edge cases:
- no data for selected period;
- negative values;
- zero values;
- multiple currencies;
- cancelled records;
- duplicated records;
- partial external response;
- delayed source data;
- missing Asset mapping;
- timezone boundary crossing;
- period boundary crossing.For financial Metrics, currency handling must be explicit. Do not mix currencies without declaring conversion logic.
For time-based Metrics, the time context must be clear. Avoid vague values such as “current month” unless the current month is defined by INTERA or by the role package’s period contract.
A good Metric should be traceable back to its source DataSource or synchronized entity. This allows administrators and developers to investigate unexpected values.
Performance expectations #
An integration should be fast enough to support normal INTERA usage and safe enough not to overload the external system.
Performance expectations depend on the integration type. A small API request, a dashboard DataSource, and a large entity sync job do not have the same performance profile.
General expectations:
- DataSources should return quickly enough for dashboard use.
- Sync jobs may take longer, but should be controlled and observable.
- Large responses should use limits, filters, or pagination.
- External systems should not be overloaded.
- Timeouts should be handled clearly.
- Repeated requests should not create unnecessary load.DataSources used directly by dashboards should be designed for interactive use. They should avoid large unfiltered responses and long-running queries.
Recommended DataSource practices:
- require date filters where appropriate;
- support limit parameters;
- use pagination for large datasets;
- return summaries when full detail is not needed;
- cache results where safe;
- avoid expensive external calls inside frequently refreshed widgets;
- include generatedAt timestamps.Entity Sync can process larger datasets, but it should still be predictable.
Recommended sync performance practices:
- use stable keys;
- process data in batches where appropriate;
- support pagination from external APIs;
- avoid duplicate records;
- log progress for long-running sync;
- report partial failures;
- avoid uncontrolled full-system imports;
- do not physically delete records unless explicitly supported.SQL/database integrations require special care. Developers should avoid unrestricted queries and long-running database operations.
Recommended SQL performance rules:
- use read-only credentials;
- use predefined queries or database views;
- validate all parameters;
- avoid full table scans where possible;
- use indexes in the source database where available;
- apply date filters;
- return predictable result shapes;
- avoid exposing arbitrary SQL execution.File-based integrations should validate file size and format before processing.
Recommended file performance rules:
- define maximum expected file size;
- validate headers before parsing all rows;
- handle empty files;
- handle duplicate rows;
- fail clearly on unsupported formats;
- avoid repeatedly processing the same unchanged file where possible.Performance testing should include both normal and larger datasets.
Recommended performance test cases:
- small response;
- empty response;
- normal expected response;
- large response;
- slow external system;
- external timeout;
- repeated calls;
- repeated sync;
- multiple Integration Instances using the same module.An integration should be considered ready for wider testing when it can run repeatedly in a trial environment, return predictable results, handle expected failure cases, and stay within acceptable response times for its intended use.
