Forge
Explanation

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 @ExtendWith extension) starts the application in beforeAll and, by design, leaves it running in afterAll so 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() calls System.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 — a JavaExec task that Forge configures on the CATIA Magic JRE with MagicDraw's vm.options. Forge registers it when com.mbseconsulting.forge.configure.testing=true and a CATIA Magic installation path is set. It sets isIgnoreExitValue = true.
  • ForgeIntegrationRunner — a small Java runner that generateIntegrationSupport generates 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

  1. 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.
  2. The runner drives the JUnit Platform launcher over the tests tagged @Tag("IntegrationTest"). A single engine selects them, so each test runs once.
  3. 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.
  4. After the test plan finishes, the runner releases the seat by reflectively calling Application.getInstance().shutdown(), which System.exit()s the fork. The report already exists on disk, so the exit loses nothing.
  5. The integrationTest task 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.

On this page