Suite
To define a suite follow the patterns below.
A suite is two entry points — one per platform — and each brings its own children. The integration
config decides which test groups the runner picks up, per platform:
Server
import {server} from '@feasibleone/blong';
export default server(blong => ({
url: import.meta.url,
validation: blong.type.Object({}), // this is not yet finalized
children: [
// import reusable realms
async function reusableRealm1() {
return import('reusable-realm-1/server.js');
},
async function reusableRealm2() {
return import('reusable-realm-2/server.js');
},
// local custom realms
'./custom-realm-1',
'./custom-realm-2',
],
config: {
// suite configs per intent
default: {},
microservice: {},
dev: {},
integration: {
watch: {
test: ['test.subject'], // what to run during integration tests
},
},
},
}));
Browser
import {browser} from '@feasibleone/blong';
export default browser(blong => ({
url: import.meta.url,
validation: blong.type.Object({}), // this is not yet finalized
children: [
// import reusable realms
async function reusableRealm1() {
return import('reusable-realm-1/browser.js');
},
async function reusableRealm2() {
return import('reusable-realm-2/browser.js');
},
// local custom realms
'./custom-realm-1',
'./custom-realm-2',
],
config: {
// suite configs per intent
default: {},
microservice: {},
dev: {},
integration: {
watch: {
test: ['test.subject'], // what to run during integration tests
},
},
},
}));
Well known reusable realms
Blong provides some reusable realms, that can be used in the suite or in other realms. For example:
@feasibleone/blong-test- helps with browser front end API testing, by providing a realm with the HTTP adapter@feasibleone/blong-login- helps with user authentication@feasibleone/blong-openapi- helps with implementing handlers for OpenAPI definitions
To use them, include them in the children property of the suite or realm, for example:
-
server.ts- defines the suite and includes the reusable realms.import {server} from '@feasibleone/blong';export default server(blong => ({url: import.meta.url,children: [async function testServer() {return import('@feasibleone/blong-test/server.js');},async function login() {return import('@feasibleone/blong-login/server.js');},async function openapi() {return import('@feasibleone/blong-openapi/server.js');},],})); -
browser.ts- defines the browser suite and includes the reusable realms.import {browser} from '@feasibleone/blong';export default browser(blong => ({url: import.meta.url,children: [async function testServer() {return import('@feasibleone/blong-test/browser.js');},async function login() {return import('@feasibleone/blong-login/browser.js');},async function openapi() {return import('@feasibleone/blong-openapi/browser.js');},],}));
Common concepts
Suites export a single function, which receives the Blong's load function as parameter and
initiates the loading of realms and optionally runs the tests. Suites are launched from the command
line, using the blong CLI tool in the suite's root folder. The load function has the following
signature:
type Load = (
definition: object,
suiteName: string,
parentConfig: string | object,
configNames: string[], // the intents to apply for this run
manifest?: Record<string, unknown>, // shared state, see below
) => Promise<{
start: () => Promise<unknown>;
test: () => Promise<unknown>;
stop: () => Promise<unknown>;
}>;
The parameters are:
definition: The server or browser definition as factory function - this is the default export of theserver.ts,browser.tsor other platform file in the suite's root foldersuiteName: The name of the suite. The name has some impact on various entities:- It determines the name of the configuration file where additional config is stored. The name
is:
.ut_<suite><env>rc, where<suite>is the lowercase suite name and<env>is the environment, for exampledevortest. - It determines the default k8s namespace where the suite is deployed.
- It determines the name of the configuration file where additional config is stored. The name
is:
parentConfig: Configuration overrides for the suite. This parameter is used to avoid the need of additional configuration files for the cases of running automated tests.configNames: The intents to apply. This activates the appropriate configurations within the realms, avoiding the need to pass them through configuration files or command line parameters.manifest: An optional shared object for exchanging runtime values between platforms — effective ports, connection strings or other lifecycle state. Pass the same reference to bothload()calls so that what one platform writes the other can read. Omit it when the suite has nothing to share.
Tests
There can be different tests, depending on what part of the functionality is tested and the specific interaction:
API tests
These tests cover part of the most common interaction - Application front ends. They simulate calls from the front end to the API gateway, without running the UI. They are faster to run and easier to debug, but they do not test the UI.
To achieve this, the browser and server platforms are loaded and the tests are initiated from the browser side. For the browser platform only the adapter, orchestrator and test layers are activated. The browser platform is chosen, as it is the best to simulate in automated tests due to these reasons:
- Fastest to run in node.js
- Closest to the most used interaction - application front running in a browser
- It uses the same components that are used in the real browser front end.
This is also the usual way to run the suite during development, as it allows for the most frequent
interactions to be developed and tested with low latency loop. As such, it is often present in the
index.ts file in the suite's root folder.
import browser from './browser.ts';
import server from './server.ts';
type Load = (
definition: object,
suiteName: string,
parentConfig: string | object,
configNames: string[],
manifest?: Record<string, unknown>,
) => Promise<{
start: () => Promise<unknown>;
test: () => Promise<unknown>;
stop: () => Promise<unknown>;
}>;
export default async (load: Load): Promise<void> => {
// The manifest is a shared object for exchanging runtime values between
// platforms (e.g. effective ports, connection strings). Pass the same
// reference to both load() calls — writes from one side are visible to
// the other.
const manifest: Record<string, unknown> = {};
const platforms: Awaited<ReturnType<typeof load>>[] = await Promise.all([
load(server, 'suite-name', 'suite-name', ['microservice', 'integration', 'dev'], manifest),
load(browser, 'suite-name', 'suite-name', ['microservice', 'integration', 'dev'], manifest),
]);
for (const platform of platforms) await platform.start();
await platforms[1].test(); // run tests from the browser side
await new Promise(resolve => setTimeout(resolve, 2000));
if (process.env.CI) for (const platform of platforms) await platform.stop();
};
Internal API tests
These tests simulate internal calls, usually to the orchestrators. To achieve this, only the server platform is loaded and the tests are initiated from the server side.
In this case, the test is wrapped in the tap testing framework, to provide some test coverage
report.
// internal.test.ts
import load from '@feasibleone/blong-gogo';
import tap from 'tap';
import server from './server.ts';
const platform = await load(server, 'suite-name', 'suite-name', [
'microservice',
'dev',
'test',
'integration',
]);
await platform.start();
await tap.test('internal api', async test => {
await platform.test(test);
});
await platform.stop();
A complete working example is in the blong-eip package.
Integration tests with real back ends
A suite whose adapters must talk to a real system — a database, a broker, a key store — is run with
the integration intent, and CI provisions those systems into a temporary cluster before the tests
start. The suite's own part of that is small: the tap entry point below, and a ci-test script that
waits for the back ends it needs.
test.ts — tap entry point for the integration run:
import load from '@feasibleone/blong-gogo';
import tap from 'tap';
import server from './server.ts';
export default async function test(intents: string[] = [], config: string | object = 'suite-name') {
const platform = await load(server, 'suite-name', config, ['integration'].concat(intents));
await platform.start({});
await tap.test('blong suite-name', async test => {
await platform.test(test);
});
await platform.stop();
}
if (import.meta.main) {
test().catch(err => {
console.error(err);
process.exit(1);
});
}
package.json — hooks the readiness gate into the Rush ci-test command:
{
"scripts": {
"ci-test": "../../test/integration/wait.sh && blong-dev test"
}
}
The other half — the manifests, the ports, the readiness gate and how to read a failure — is in integration tests with real back ends.
Realm configuration — the test and sim layers are only activated under adapter.xxx:
config: {
default: {},
microservice: {adapter: true},
'adapter.xxx': {test: true, sim: true},
}
Suite server.ts — declare which test handlers to run via the watch.test list:
config: {
'adapter.xxx': {
watch: {
test: ['test.xxx.case1', 'test.xxx.case2'],
},
},
},
A complete working example is in the blong-int-adapter package.
UI tests
These tests run the full browser app and simulate user interactions with the UI. They are slower to run and harder to debug, but they test the UI as well.
This is not yet implemented, as the front end framework is not yet ready, but the idea is to run the tests from the browser side, using a test runner like Playwright.
Edge device tests
These tests simulate interactions from edge devices such as ATMs, POS terminals, or IoT devices. They initiate requests at the TCP/binary protocol level rather than at the HTTP API level.
This is not yet documented. For protocol-level simulation patterns see the
blong-sim-tcp package and the
blong-codec skill.