Integration testing with CATIA Magic
Why an integration test against CATIA Magic runs in a forked JVM.
This page explains why integration tests against CATIA Magic need special handling and how Forge runs them. For the steps to write and run such a test, see Write tests.
The problem
Integration tests exercise the MagicDraw Open API, so they require a running MagicDraw application (Cameo Systems Modeler / Magic Cyber Systems Engineer). MagicDraw checks out a floating licence seat when it starts.
Three constraints make this hard to run under a normal test task:
- The test extension starts MagicDraw but never stops it.
com.nomagic.magicdraw.tests.MagicDrawApplication(the JUnit 5@ExtendWithextension) starts the application inbeforeAlland, by design, leaves it running inafterAllso later test classes can reuse it. - Only a full shutdown releases the seat. Dassault surfaces no API to release the licence seat on
its own. The seat is released only by
com.nomagic.magicdraw.core.Application.shutdown(). - Shutdown terminates the JVM.
Application.shutdown()callsSystem.exit(). On JDK 21 the runtime offers no supported way to intercept that exit.
These combine into a dilemma. A test JVM that leaves MagicDraw running leaks the licence seat. A test
JVM that shuts MagicDraw down exits through System.exit() before the test framework finalizes its
results, so Gradle fails the task even when every test passed.
The solution
Forge runs integration tests in a dedicated forked JVM and reads the outcome from a report file
on disk. The licence-releasing System.exit() therefore destroys no result data, and the task
outcome does not depend on the fork's exit code.
Components
integrationTest— aJavaExectask that Forge configures on the CATIA Magic JRE with MagicDraw'svm.options. Forge registers it whencom.mbseconsulting.forge.configure.testing=trueand a CATIA Magic installation path is set. It setsisIgnoreExitValue = true.ForgeIntegrationRunner— a small Java runner thatgenerateIntegrationSupportgenerates into the consumer's test sources. It runs inside the fork and owns the whole test lifecycle.
The task also carries an onlyIf guard that skips it when no test source declares
@Tag("IntegrationTest"). The guard exists because the report alone cannot distinguish a project
that owns no integration suite from a run that was configured wrong and executed nothing — both
leave tests=0 in the report. Deciding before the fork separates them, and costs no licence to find
out.
How a run proceeds
- The runner clears stale reports from
build/test-results/integrationTest, so a crashed or empty run cannot be read as an earlier run's success. - The runner drives the JUnit Platform launcher over the tests tagged
@Tag("IntegrationTest"). A single engine selects them, so each test runs once. - As each test finishes, the runner writes the running result to a JUnit XML report using plain file I/O. The write happens during execution, before any teardown.
- After the test plan finishes, the runner releases the seat by reflectively calling
Application.getInstance().shutdown(), whichSystem.exit()s the fork. The report already exists on disk, so the exit loses nothing. - The
integrationTesttask ignores the fork's exit code, reads the report, and fails on any failure or error, or when no test ran. The failure message lists each failed case with its exception type and message, up to ten.
A class whose @BeforeAll throws runs none of its tests, and JUnit reports the failure on the class
alone. The runner records it as an error named classMethod in that class's report, with the
exception's message and stack. The same holds for a failing @AfterAll. A broken setup therefore
fails the task and names its cause, and a class whose setup fails never drops out of an otherwise
passing run.
Writing results as each test or class finishes, rather than after the whole run, is load-bearing.
The test extension leaves MagicDraw running between classes, and the runner shuts it down only after
launcher.execute() returns. A fork that ends earlier, through a crash or through code that calls
Application.shutdown() itself, loses every result not yet on disk, so writing early bounds that
loss to the test in flight.
What a consumer writes
A consumer tags each integration test @Tag("IntegrationTest") and annotates the class with
@ExtendWith(MagicDrawApplication::class). It writes no test suite and no shutdown code; Forge owns the
fork, the report, and the licence release.
Why the resource is installed first
A .mdzip records each used project twice: an identity, and an absolute path written by whoever
saved the model. MagicDraw resolves the identity against the CATIA Magic installation first, and a
copy sitting there wins even when the recorded path still resolves on the machine running the test.
Without an installed copy, a second checkout either fails to load the profile, because the recorded path names a directory that checkout does not have, or silently loads a different checkout's copy, because that path still resolves there and nothing tells the test whose profile answered. Either way the suite's result depends on which machine, or which clone, happens to run it.
Forge removes that dependency by installing the assembled resource into the CATIA Magic installation
before the fork and removing it afterwards, and that installed copy is why integrationTest depends
on the assembly chain: the resource being installed has to exist first.
The installed copy is per-project, disposable state that exists only for the fork's duration. A consumer never installs its own working resource this way; that path stays reserved for what Forge installs and removes on the test's behalf.