Cross-Platform Testing Framework

Relevant source files

The following files were used as context for generating this wiki page:

• tests/cross-platform-framework.ts
• tests/appium-driver.ts
• tests/playwright-driver.ts
• tests/e2e/cross-platform/multi-platform.e2e.test.ts
• E2E_IMPLEMENTATION_SUMMARY.md
• tests/README.md
• E2E_TEST_STATUS.md
• tests/scripts/validate-e2e-framework.js

The Cross-Platform Testing Framework is a specialized system designed to facilitate end-to-end (E2E) integration tests across Web, Android, and iOS platforms. It provides a unified API to abstract away the complexities of different test drivers (Playwright for web, Appium for mobile), allowing developers to write consistent test logic for complex multi-platform scenarios, such as peer-to-peer messaging and mesh networking.

The framework is designed to be complete, maintainable, and scalable, supporting real network conditions without mocking. For more information on running tests, see the E2E Testing Guide.

Sources: E2E_IMPLEMENTATION_SUMMARY.md, E2E_TEST_STATUS.md

Architecture

The framework is built on an abstraction layer that separates test orchestration from platform-specific automation. The main components are the CrossPlatformTestCoordinator, which manages the test lifecycle, and the PlatformClient interface, which defines a common set of actions for any client application.

Sources: tests/cross-platform-framework.ts, E2E_IMPLEMENTATION_SUMMARY.md

Component Diagram

This diagram shows the class hierarchy and relationships between the core components of the framework.

Core Components

The framework consists of a central orchestrator and several platform-specific client drivers.

Sources: tests/cross-platform-framework.ts

CrossPlatformTestCoordinator

This class is the central orchestrator for all cross-platform tests. It is responsible for creating, connecting, and cleaning up platform clients. It also provides high-level helper methods for common test actions like sending and verifying messages.

Key Methods:

Method	Description
createClient(options, ...)	Creates a platform-specific client (Web, Android, or iOS).
connectClients(client1, client2)	Establishes a connection between two clients.
sendAndVerifyMessage(sender, receiver, message, timeout)	Sends a message from one client and verifies its receipt by another.
waitForMeshNetwork(expectedPeers, timeout)	Waits for a client's mesh network to reach an expected number of peers.
cleanup()	Terminates all clients and cleans up resources.

Sources: tests/cross-platform-framework.ts, E2E_IMPLEMENTATION_SUMMARY.md

PlatformClient

This is an abstract class that defines the common interface for all platform clients. Any new platform added to the testing framework must implement this interface, ensuring a consistent API for test scripts.

Abstract Methods:

Method	Description
sendMessage(contact, message)	Sends a message to a specified contact.
waitForMessage(message, timeout)	Waits for a specific message to be received.
addContact(name, publicKey)	Adds a new contact to the user's contact list.
getPeerCount()	Returns the number of connected peers in the mesh network.
goOffline() / goOnline()	Simulates the client going offline or coming back online.

Sources: tests/cross-platform-framework.ts, E2E_IMPLEMENTATION_SUMMARY.md

Client Implementations

• WebClient: An implementation of PlatformClient that uses Playwright to automate a web browser instance.
• AndroidClient: An implementation that uses Appium and the UiAutomator2 driver to control an Android device or emulator.
• iOSClient: An implementation that uses Appium and the XCUITest driver to control an iOS device or simulator.

Sources: tests/cross-platform-framework.ts, E2E_IMPLEMENTATION_SUMMARY.md, E2E_TEST_STATUS.md

Test Execution Flow

A typical cross-platform test involves creating multiple clients, connecting them, performing actions, and verifying the outcomes.

This sequence diagram illustrates a test where a message is sent from a Web client to an Android client.

Configuration

The mobile testing aspect of the framework relies on Appium, which is configured in appium.config.ts. This file specifies server details and capabilities for both Android and iOS platforms.

// Source: appium.config.ts (as described in E2E_IMPLEMENTATION_SUMMARY.md)
export const config = {
  server: { host: 'localhost', port: 4723 },
  android: {
    platformName: 'Android',
    automationName: 'UiAutomator2',
    deviceName: 'Android Emulator',
    platformVersion: '13',
    app: './android/app/build/outputs/apk/debug/app-debug.apk',
    autoGrantPermissions: true,
  },
  ios: {
    platformName: 'iOS',
    automationName: 'XCUITest',
    deviceName: 'iPhone 15',
    platformVersion: '17.0',
    app: './ios/build/.../SovereignCommunications.app',
  },
};

Sources: E2E_IMPLEMENTATION_SUMMARY.md, E2E_TEST_STATUS.md, tests/scripts/validate-e2e-framework.js

Test Suites

The framework is used to write several categories of E2E tests, which are organized by the platforms they involve.

• Web-to-Web: Tests messaging between two web browser instances.
• Web-to-Android: Tests cross-platform messaging between a web client and an Android client.
• Web-to-iOS: Tests cross-platform messaging between a web client and an iOS client.
• Multi-Platform Mesh: Tests complex scenarios involving a mesh network of four or more nodes across all three platforms (Web, Android, iOS).

Sources: tests/README.md, E2E_IMPLEMENTATION_SUMMARY.md, tests/e2e/cross-platform/multi-platform.e2e.test.ts

Usage Example

The following snippet from a multi-platform test demonstrates how the CrossPlatformTestCoordinator is used to set up a 4-node mesh network for testing.

// Source: tests/e2e/cross-platform/multi-platform.e2e.test.ts
test('should establish 4-node mesh network', async ({ browser }) => {
  const coordinator = new CrossPlatformTestCoordinator();
  
  // Create 4 clients across platforms
  const webClient1 = await coordinator.createClient({ platform: 'web', name: 'web-alice' }, ...);
  const webClient2 = await coordinator.createClient({ platform: 'web', name: 'web-bob' }, ...);
  const androidClient = await coordinator.createClient({ platform: 'android', name: 'android-charlie' });
  const iosClient = await coordinator.createClient({ platform: 'ios', name: 'ios-david' });
  
  // Connect all in mesh topology
  await coordinator.connectClients(webClient1, webClient2);
  await coordinator.connectClients(webClient1, androidClient);
  // ... more connections

  // Wait for mesh to stabilize
  await coordinator.waitForMeshNetwork(3, 60000);
  
  // Verify all nodes connected
  for (const client of coordinator.getAllClients()) {
    const peerCount = await client.getPeerCount();
    expect(peerCount).toBeGreaterThanOrEqual(3);
  }
  
  await coordinator.cleanup();
});

Sources: E2E_IMPLEMENTATION_SUMMARY.md, tests/e2e/cross-platform/multi-platform.e2e.test.ts

CI/CD Integration

The E2E tests are integrated into the GitHub Actions CI/CD pipeline, with different jobs for different test scenarios to optimize for speed and resource usage.

This diagram shows the flow of the E2E testing pipeline.

Summary

The Cross-Platform Testing Framework is a critical piece of infrastructure that ensures the reliability and correctness of the Sovereign Communications application across all supported platforms. By providing a unified API, it simplifies the creation of complex E2E tests and enables automated verification of real-world user journeys involving peer-to-peer and mesh networking. Its integration into the CI/CD pipeline allows for continuous validation of application behavior.

Sources: E2E_IMPLEMENTATION_SUMMARY.md, CONTRIBUTING.md