LibreSocial · Documentation

Tester — the master/slave benchmark harness (and the JUnit bundle)

Deep-dive page: the two test-support bundles Source/com.p2pframework.tester (OSGi bundle id com.p2pframework.tester.component) and Source/com.p2pframework.unittests, plus the load-generation message com.p2pframework.message.TestCaseCommandMessage that lives in the framework bundle com.p2pframework.

Status note: this is not a unit-test suite or a CI fixture. It is a testbed load generator and measurement driver written by the University of Paderborn project groups 2011–2014 (PG 2011, PG 2013) and then kept alive by six successive theses (Liu 2013, Peng/Balabhadruni 2014, Kaneirya 2015, Dlikman 2018, Khitman 2020, Imam 2025). The code in the tree today is that Paderborn design, migrated to Java 17/Gradle+bnd in 2026 — no redesign has happened.

Purpose

  1. Drive many real node instances through realistic application-level behaviour. One node acts as master, the others as slaves. The master distributes a test plan — a sequence of plugin operations (wall posts, photo uploads, friend requests, group joins, forum threads, votes, calendar events, file uploads, searches, logins/logouts) — and each slave executes it against the live plugin stack, so the overlay, messagedispatcher, storagedispatcher and DDS are exercised end to end.
  2. Make the load reproducible and comparable. Plans are plain text files (static plan, timed plan with repetitions + time slots, start script for new users), and workload parameters (online duration, friend count, category switching) come from frequency-distribution files.
  3. Measure while generating. The harness starts/stops the monitoring over-overlay and reads its global metrics (GLOBAL_*), so a run yields per-node statistics files that are then collected and plotted.
  4. com.p2pframework.unittests serves a different, secondary purpose: JUnit 4 tests for framework internals (DDS, PAST, Scribe/aggregation, Pastry ring/NAT/STUN, search, login/roles) plus an in-process DDS node simulation used for data-distribution measurements.

Current implementation (as of 2026)

Build and packaging (verified in the working tree)

Aspect State today
Gradle module settings.gradle:33 (:com.p2pframework.tester), :85 maps it to Source/com.p2pframework.tester; :34/:86 do the same for :com.p2pframework.unittests
Bundle ids com.p2pframework.tester.component;singleton:=true (note: the bundle id differs from the folder name), com.p2pframework.unittests v0.0.1
Execution env Bundle-RequiredExecutionEnvironment: JavaSE-17 in both bnd.bnd files (git: "Replace JavaSE-1.7 with JavaSE-17 in all bnd files", 2026-06-09)
Activation tester: Bundle-ActivationPolicy: lazy, -dsannotations: * (declarative services); exports …component, interfaces, master, preconditions, singletons, testcases
Compile status ./gradlew :com.p2pframework.tester:compileJava and :com.p2pframework.unittests:compileJava both succeed (exit 0) on the 2026 branch; only deprecation/unchecked notes, plus Thread.suspend() "marked for removal" in com/p2pframework/groups/GroupsTest.java:258
Runtime assembly Neither bundle is in the launcher runtime: cnf/org.libresocial.launcher.common.bndrun -runrequires/-runbundles list 30+ bundles (core, plugins, com.p2pframework.monitoring, rice.freepastry, …) but no tester and no unittests. TestComponent therefore only activates if the bundle is deployed and enableTestPlugin=true
CI .gitlab-ci.yml has two stages only (prepare-runtime → build-image, eclipse-temurin:21 + podman/docker). No test stage at all, so nothing runs JUnit or the tester in CI
Gradle test task wired to source dirs unitTests/ and test/ (see build-logic/src/main/groovy/osgi-bundle-conventions.gradle); com.p2pframework.unittests keeps all JUnit classes in src/, i.e. in the main source set → :com.p2pframework.unittests:test executes zero tests (no build/test-results produced)

com.p2pframework.tester — 13 packages, key classes

Path under src/com/p2pframework/tester/ Lines Role
component/TestComponent.java 573 @Component(name=…, service=CommandProvider.class), extends AbstractUIPlugin. activate() returns immediately unless ConfigLoader.isTestPluginEnabled(); then it enables debug mode, injects 13 plugin services into PluginProvider, and decides master vs slave via checkMasterOperations()/isMaster() before starting the thread. Registers Equinox console commands and tray menu items "Testplugin MasterView"/"Testplugin DelegaterView"
master/Master.java 311 MasterOperations, Runnable, TestCaseParticipant. Keeps the bootstrap-server, registered-user, online-user and used-port lists; getBootstrapServerList() appends ownIP + ":9001"; run() logs in admin/admin through the login/profile plugins, binds the RMI stub, then if (ConfigLoader.getIntConfigProperty("autoStartMonitoring") == 1) MonitoringPlugin.getInstance().startMonitoring();
slave/Slave.java 286 Runnable, TestCaseParticipant, ReceiveCallback<String, Message>. init(): sleep startupDelay, either TestCaseRegister (random login) or TestCaseLogin(server, masterPort, ownIP, freePort, user, pass), then subscribe to the topic channel TestPluginTopicChannel. Loop: random mode → memoryClean(), start-script for new users, SlaveLogoutTimer scheduled at chooseOnlineDuration(); logoutLogin() re-registers after a jitter of (port*port % 270)*27 ms and re-logs in directly against the master IP (workaround for a vanished bootstrap node)
slave/TestPlan.java 427 The execution engine: LinkedList<String> plan, control commands, reflective instantiation Class.forName("com.p2pframework.tester.testcases." + name).getConstructor().newInstance() (2026 code already uses instanceof TestCase case1 pattern matching), post-case jitter, exception accounting, timed plan, random selection
singletons/ConfigLoader.java 549 Own config reader (resources/config.txt), masterPort = 9001, slaveStartPort = 10005, portRange = 1000, getFreePort() steps by 2 with a ServerSocket+DatagramSocket probe, sets java.rmi.server.hostname to the own IPv4 address, creates/looks up the RMI registry, and isMaster() = "the configured server IP is one of my own local IPv4 addresses"
singletons/ParameterGenerator.java 1255 ~70 workload-parameter helpers: chooseOnlineDuration(), chooseUsersFriend(), chooseFriendshipCandidate() (master's online users minus self/friends), chooseGroupMembershipCandidate(), name/message/subject/album/picture/file/interest generators, plus cached plugin state (loadFriendList, loadCurrentUsersAlbums, loadGroups, loadForum, loadCalendar, loadUsersVotings) with "loaded" flags
singletons/ConditionVerifier.java 392 Synchronized existence checks over StorageKeys: album, group, vote, inbox message, photo, folder/file, forum thread, calendar event, wall post, friendship, login state, "friendlist loaded", plus hasNewUserRegistered()/setNewUserRegistered()
singletons/ResourceLoader.java 411 Loads every resources/*.txt; expands percent:value lines into sample arrays (range = 100 * percent), builds per-friend multiplicity arrays, parses case:category
singletons/TestCaseRegistry.java 100 category → test-case list from testCaseRegistry.txt; getRandomTestCaseOfCategory(), getRandomTestCase()
singletons/CategoryDistribution.java 147 Category switching model (see Technical details)
singletons/PluginProvider.java 193 Static holder for the 13 bound services (login, profile, friends, photos, wall, live chat, calendar, groups, forum, messaging, vote, search/messageDispatcher, commands, Framework)
testcases/ 57 files 56 concrete test cases + abstract TestCase
preconditions/ 28 files 27 preconditions + abstract Precondition
interfaces/ 2 MasterOperations (RMI: bootstrap-list CRUD, isUserRegistered/registerUser, online/registered user lists, used-port list) and TestCaseParticipant (sendTestCaseCommand(int, String, Priority, Collection<String>), toggleParticipantView())
util/ 3 PluginPropertiesContainer (PluginID = "TestPlugin", TopicChannelName = "TestPluginTopicChannel"), SkipRepetitionsTimer, SlaveLogoutTimer
views/ 4 SWT MasterView and TestCaseDelegaterView + toggle handlers

Counts match what the theses reported: Khitman 2020 documents 56 test cases and 27 preconditions.

Resources (resources/)

com.p2pframework.unittests

≈50 Java files, 228 @Test methods, 12 @Ignore, JUnit 4 (junit:junit:4.13.2 in build.gradle, Require-Bundle: org.junit in bnd.bnd), plus lib-dist jars (FlexiProvider, kryo-3.0.0, guava-10.0.1, CoDec, objenesis, reflectasm) and an SWT dependency (org.eclipse.swt is even imported by GroupsTest).

Area Classes
DDS (largest block) DistributedLinkedListTest (693 l), DistributedLinkedList_DistributionTest (268), DistributedSetTest (466), SecureDistributedSetTest (501), DistributedTreeTest (290), SecureDistributedTreeTest (308), PrefixHashTrieTest (316), WriteProtectionDistributedList (297), UltimateEvaluation (368)
Overlay / transport network/freepastry/{PastryNetworkTest, PastryIDTest, IPCacheTest, RateBufferTest}, ring/{TestPastryRingManager, TestPastryRingLifenessChecker, TestPastryRingIdentifiactionTransportLayer, TestGettingExternalIpAddress}
NAT / STUN network/freepastry/nat/{CheckConnectivity, CheckStunNatTypeDetection, CheckStunPort, DirectCommunicationTest, StunLifenessCheckerTest, TraversalStrategyTest, …}
Messaging message/scribe/{PastryMessageChannelTest, PastryTopicChannelTest}, message/aggregate/AggregationTest, messaging/MessagingTest, friends/test_Junit, groups/GroupsTest, calendar/calendarTest, login/{LoginTest, SimpleRoleRightsTest}
Storage / search / misc storage/past/*, search/{JoinQueryEngineTest, ScribeQueryEngineTest}, network/freepastry/past/replication/Replication, security/AsymmetricKeyTest, stream/freepastry/PastryFileTransferTest, appstore/PublicAppstoreTest, ConfigurationTest, errorhandling/ErrorHandlingTest, com/common/utilities/HierarchicalPropertiesTest

UltimateEvaluation is an in-process simulation, not a JUnit test: remote = false, numberOfNodes = 10, splitSize = 100000000, listHash = "DistributionTest_List", an ArrayList<TestNodeEvaluation> nodeList, and bucket inspection through DistributedDataBucket/DistributedDataItemContainer. Its output path is hard-coded to C:\Daten\PG_Lifesocial\Git\Evaluation\ and the comment in the source says it is "only for non-remote simulation" — it must be edited before it runs on Linux.

Its resources/ hold a legacy plan format from before the current TestPlan grammar (doXTimes N $RANDOM_INT PhotosPlugin.AddPhoto $ALBUMKEY#$GROUPNAME#$PICTURE#$MESSAGE, sendFriendRequestsToAll, acceptAllFriendRequests, monitor start), a config.txt with server=131.234.75.22, master=true, freepastry.params, and ring/bootstrap XMLs (temp/{rings,bootstraps}.xml, unitTests/rings.xml). They are stale configuration, not fixtures consumed by a Gradle task.

Design options and decision

The source contains no alternative-design discussion; the options below are reconstructed from the cited theses, which do discuss the setup, its weaknesses and the changes they made. Where a paper states the trade-off explicitly this is noted.

1. Control plane: one central master (RMI + Scribe) vs. per-node scheduling vs. an external driver. Chosen: central master. It gives a single place to distribute plans, collect user/port/bookkeeping state and start monitoring — which is what the reproducible, comparable runs of Liu 2013 and Dlikman 2018 require. Two channels are used for different reasons: RMI (LocateRegistry.createRegistry(Registry.REGISTRY_PORT) = 1099, name MasterOperations) for synchronous bookkeeping queries, and the Scribe topic channel TestPluginTopicChannel for asynchronous, fire-and-forget plan distribution. Costs are known and were reported at the time: the master is a single point of failure (slave code re-logs in directly against the master IP when the bootstrap is gone; Liu flagged the RMI lookups used for friend-request targeting as a weakness), and there is no unique master↔slave assignment, which Khitman 2020 lists as required future work before several test instances can share a cluster. Simulation (PeerSim/OverSim-style) was rejected implicitly: the whole point is to benchmark a real FreePastry/OSGi deployment, as the 2020 evaluation paper argues.

2. Workload: deterministic plan vs. random walk vs. timed plan. All three ship, because they answer different questions. testplan.txt gives reproducibility; the timed plan (Nx TestCase 5m) gives a rate and keeps repetitions inside a time slot; random mode gives realism. The random model is not invented in code: it is a category-transition (Markov-style) model whose shape follows the pseudo-random behaviour algorithm of a user study with >35 000 users, as used in Khitman 2020 and Newton 2020. The failures are documented rather than hidden: with enableAutomaticLogout=true all nodes died ≈2.5 h after plan start (Khitman attributes this to the randomization algorithm), and random mode with churn lost 0.5–1.7 % of messages while the timed synthesis test lost none (Peng/Balabhadruni 2014). Reconstructed reading: random mode remained a research instrument rather than a stable product feature.

3. Test-case glue: preconditions with executable fallbacks vs. fixed fixtures. Chosen: TestCase.executeTestCase() runs checkParameters → generateMissingParameters → checkPreconditions → fulfillPreconditions → execute(), where fulfillPreconditions() runs another test case (e.g. create the album before uploading a photo) and ConditionVerifier confirms it by looking up StorageKeys on the live DHT. That makes an arbitrary sequence of remote commands runnable on a node whose state you do not control — necessary because slaves join, leave and re-register. Cost (documented by Peng/Balabhadruni 2014): preconditions inject extra load, and shared ParameterGenerator state coupled test cases; cleaning those globals was one of their fixes, and case independence visibly cut exception counts (≈80 NPE + 120 others at 10 instances in round 1).

4. Measurement: reuse the shipped monitoring over-overlay vs. an external collector. Chosen: reuse com.p2pframework.monitoring, i.e. the tree-based monitoring derived from the DHT key space (SkyEye 2017: UI = 30 s, β = 4, ≈512 B/min/peer, ±0.1 accuracy versus ±0.7 for gossip push-sum), so the benchmark observes the system through the same instrumentation the product uses. The alternative — a central collector — is exactly what the project avoids everywhere else; gossip-based aggregation is discussed and discarded in Dlikman 2018. Known coupling risk: the harness starts monitoring itself (autoStartMonitoring), and monitoring was itself a defect source — the MonitoringPluginHandler leak (historySize 200 → 1) and growing FreePastry memory ended the 5300-minute run with a message-queue overflow in PriorityTransportLayer (Peng/Balabhadruni 2014); Kaneirya 2015 later measured much lower memory once SQLite output replaced the visualizer, and enlarged/prioritized the transport queues.

5. Test-case binding: reflective instantiation from plan text vs. typed command registry. Chosen: reflection on "com.p2pframework.tester.testcases." + name. Plans are therefore plain text distributable over HTTP without recompiling any node — the practical requirement behind Schulte 2015's remote-operated setup. Cost: no compile-time binding, so renamed plugin APIs silently break cases; Khitman 2020 measured 28 of 56 cases (50 %) broken or unrunnable and fixed them; the 2014 team had found 19 of 26 broken. com.p2pframework.unittests is the counter-model (typed JUnit calls, but single-process and never run automatically), and its stale resources/testplan.txt shows the command syntax this harness superseded.

Technical details

Role selection. ConfigLoader.isMaster() is true when the server IP from config.txt is one of the node's own IPv4 addresses. TestComponent.activate() then either binds MasterOperations or looks it up (LocateRegistry.getRegistry(server, Registry.REGISTRY_PORT).lookup("MasterOperations")).

Ports. Bootstrap/application port 9001 (masterPort default; the master appends ownIP + ":9001" to the bootstrap list), slave bind ports from slaveStartPort = 10005 inside portRange = 1000, stepping by 2, each validated by binding a ServerSocket and a DatagramSocket. RMI registry on Registry.REGISTRY_PORT (1099) with java.rmi.server.hostname forced to the own IP — so RMI through NAT will not work; this is the same NAT problem Kaneirya 2015 reports for overlay joins.

Distribution message. com.p2pframework/src/com/p2pframework/message/TestCaseCommandMessage.java (extends MessageImpl): repetitions, testCase, recipients, and enum Priority { HIGH, LOW, NEW_PARTICIPANTS_ONLY }. Slaves filter on recipients.contains("all") || contains(username); NEW_PARTICIPANTS_ONLY combined with ParameterGenerator.hasNewUserRegistered() drives the start script for freshly registered users.

Plan grammar. TestPlan.executeCurrentTestCase() interprets these strings before falling through to TestCase* classes: EnableRandomMode, DisableRandomMode, RandomTest, Wait, PrintTestPlan, ClearTestPlan, LoadTestPlan, ExecuteTimedTestPlan, RemoteLogout (runs TestCaseLogout, disables automatic logout, clears the plan). Any line starting with TestCase is instantiated reflectively; lines with Logout in the name clear the plan. After each case the slave sleeps minSleep + rnd(maxSleep - minSleep). loadPlan() parses Nx Name lines; executeTimedTestPlan() splits Nx TestCase 5m (split("x "), then name and time, minutes → ms), schedules SkipRepetitionsTimer(this) at the slot end, and loops repetitions until the flag is raised or memory runs out.

Random selection. chooseNextRandomTestCase(): pick a category with CategoryDistribution.getCategory(formerCategory), then a case from TestCaseRegistry.getRandomTestCaseOfCategory(). The matrix in CategoryDistribution has seven states — Initial (Wall 0.23, Photos 0.09, ProfilesAndFriends 0.64) and sticky self-transitions Wall 0.67, Communities 0.82, Photos 0.86, Search 0.71, Messages 0.71, ProfilesAndFriends 0.69, plus a 0.03 baseline to every category; the probabilities are expanded into a 100-entry list sampled uniformly. Churn comes from onlineDuration.txt (SlaveLogoutTimer), registration from enableRandomLogin=true (TestCaseRegister), social-graph growth from friendFrequency.txt.

Console surface (TestComponent, Equinox CommandProvider; the 2026 console is reachable over the .env-configured telnet port, and compose.yaml publishes 10001): _Test, _RandomTest, _StopRandomMode, _executeTimedTestPlan, _Login, _Logout, _LogOutAllSlavesIncrementally, _LogRandomSlavesOut, _sendFriendRequest, _sendFriendRequestInOrder, _ToggleDelegaterView, _Memory, _Quit. Master.logSlavesOut(int) chooses random online users, or all of them.

Failure accounting. A NullPointerException inside a test case increments a counter that is pushed into the framework via PastryMessageDispatcher.setNullCounter(…); any other exception goes to setOtherExceptionCounter(…); both appear as GLOBAL_* metrics, which is why "exceptions ≈ 0" is a health gate in Imam 2025. Memory guards in TestPlan: memoryClean() triggers System.gc() when free < total/3; memoryUsageDetect() returns true (skipping the remaining repetitions of the current time slot) when free < total/15.

Measurement path. monitor [start|stop|status|gui|metricName:] in com.p2pframework.monitoring/console/MonitorCommands.java; StatisticWriterServiceImpl writes to <workingDir>/SkyEyeData/Monitoring/Statistics as SQLite plus *GNUPlot.dat/CSV series, which the tester's Shell_Scripts/GatherStatisticData harvests per node. Metric names were reshaped by Peng/Balabhadruni 2014 (STORAGE_DATA_SENT/RECEIVED → STORED/RETRIEVED, plugin prefix FRAMEWORK_ → STORAGEDISPATCHER_STORAGE_, information-cache metrics dropped) and extended by Khitman 2020 (NETWORK_LEAFSET_SIZE, NETWORK_ROUTING_TABLE_SIZE). Replication degree is coupled to the leafset (RF = leafset/2 + 1, set in freepastry.params/LibreSocialConfig.txt) — that is the parameter the harness is usually swept over.

Scale actually exercised. 10–20 desktop machines (2014), 8 PCs (2018), HHU HPC "HILBERT" up to 2000 concurrently logged-in nodes across 4000 cluster slots (2020), and a 2-node LAN baseline with ~900 gnuplot diagrams per run (2025: steady-state median 846.17 MB per node, 0 exceptions, 0.20 msg/s, 65.60 KB/s overlay, 1 hop, 11.50 ms lookup, 0.048 s store). No 2026 harness for clusters or WAN exists in the tree.

Evolution and supersession

When Change (git/thesis evidence)
2011/12 (PG 2011, report 2012) Test-plugin concept appears as a framework concept and appendix manual; com.p2pframework.unittests present from the initial repository commit (2011-07-08)
2013/14 (PG 2013, report 2014) 26 test cases; timed test plan with repetitions/case/time-limit and console commands executeTimedTestPlan, sendFriendRequestInOrder; trial with 1 master + 5 slaves (i7-2600, 8 GB, openSUSE 12.3, Java 1.7.0_51); parallel/iterative Pastry routing switched off, search timeout 5 s
2013 Liu 2013: synthesis/random/long-term/alpha test taxonomy, new FRAMEWORK_*_PLUGIN*, _DDS, STORAGE_DATA_*, PASTRY_DATA_* metrics, monitor + MetricName command, ≈1500 min stability, first queue-overflow observations
2014 Peng/Balabhadruni 2014: 19 of 26 cases rewritten, metric cleanup, Master-/Delegater-View control of slaves, synthesis test on 20 × i7-2600, random+churn still lossy, 5300 min (88.3 h) long-term run, MonitoringPluginHandler leak found with JProfiler
2015 Schulte 2015: public/remote testing, 10 bootstrap VMs, shell-driven remote control (new script, reset, exec), kryo replacing XML serialization (512 KB object ≈2 ms vs ≈500 ms), SQLite monitoring files. Kaneirya 2015: GUI test 6 real nodes 15–18 h; 10 instances × 10 VMs, ≈5520 min with 0 message loss, join ≈7.8 s; enlarged prioritized transport queues; NAT identified as main operational problem
2016 git: master own-IP discovery fix, RMI exception on slave connect removed, random delay moved before test cases, LogoutLogin spreading, new deployment config, monitoring data path changed
2018 Dlikman 2018: 8-PC LAN, availability/scalability/robustness scenarios; saturation at ≈44 photos or 30 files per 8 min, storagedispatcher saturates ≈90–100 KB/s (messagedispatcher up to 1.7 MB/s), 33 % churn collapses availability to 0 % in the 4th cycle; regression test exposes metric-naming inaccuracies
2020 Khitman 2020: 28 of 56 cases fixed, 2 new network metrics, randomTest command, 500-node random run and 1000-node stability run, RF sweep (RF 16 best ≤2000 nodes, RF 32 unstable). Also the methodology statement in Newton 2020 / the 2020 paper (5 s monitoring into SQL, master/slave roles, workload/system/environment parameters)
2025 Imam 2025: revival on current hardware; ≈120 fixes, runs/<id>/{configs,metrics,plots,README.txt} layout, plot_all.sh over ≈900 plots, discipline rules (exactly one controller, ≥5 min warm-up, fixed seeds, NTP, health gates), scenarios S1–S3 with k=3/k=5 skipped because N<k. Repo git: exception-handling fix (2025-04-10), Java-version compatibility (2025-04-16), smaller test images (2025-04-17)
2026 Gradle + bnd migration: "Add support for building with gradle", "Remove old Eclipse artifacts" (2026-04-23), "Introduce bnd.bnd and bndrun files" (2026-05-18), ./gradlew rewriteRun (OpenRewrite: diamond operators, instanceof pattern matching in TestPlan), "Replace JavaSE-1.7 with JavaSE-17 in all bnd files" (2026-06-09), "Resolves but fails at :prepareOsgiRuntime later on" (2026-06-15). unittests also gained the FlexiProvider jar on the bundle classpath (2026-06-09) and a bucket-consolidation trigger (2026-07-10)

What is superseded but still in the tree — treat these as historical, not as working configuration: the UPB server=131.234.31.140 / 131.234.75.22 addresses and the szewior.de plan URLs, the Shell_Scripts/ for pgf01..pgf20, the 2013-era command syntax in com.p2pframework.unittests/resources/testplan.txt, and the Windows path in UltimateEvaluation. The JDK 1.7.0_80 + Eclipse Indigo recipe of Imam 2025 is itself superseded by the JavaSE-17 bnd migration; the 2025 setup guide predates it.

What is still missing in 2026 (also named as future work in the theses): a unique master↔slave assignment allowing parallel test instances; the broken random-mode + automatic-logout combination; negative/fault-injection tests; any CI execution (the pipeline builds a Docker image only, and the tester/unittests bundles are not in the launcher bndrun); container- or cluster-scale testbeds for the harness — compose.yaml starts a single node (ports 8443 UI, 10001 console, 9001 overlay), which cannot exercise the master/slave machinery as-is. Practical 2026 checklist to run it at all: add com.p2pframework.tester to the runtime bundle set, serve the plans from file:/… or a local HTTP server, set server to one participant's own IP, open TCP 1099 and the 9001/10005+ range, and use autoStartMonitoring=1 so metrics exist.