Magik’s Exceptions: How to Test Them in Emacs

Exception handling is essential in Magik applications that work with Smallworld databases, network services, record collections, and long-running administrative processes. A routine that fails safely is easier to support than one that returns an ambiguous value or leaves a transaction half complete. Testing those failure paths in Emacs gives developers a repeatable way to inspect the condition, verify the message, and check what the application does afterwards.

Emacs is particularly useful because it can combine Magik source editing with an inferior Magik process, compilation-style error navigation, debugger interaction, and project notes. That makes exception tests part of the normal development cycle rather than an occasional exercise performed manually in a live environment.

Understand The Failure Contract

Before writing a test, define what the Magik method promises when something goes wrong. A missing record might raise a specific condition, while invalid user input may be reported through a different condition or returned as a status value. The test should reflect that contract rather than merely checking that “some error” occurred.

Magik exception syntax and condition names can differ according to the Smallworld product version, framework conventions, and local codebase. Teams commonly use a _try block with a _when handler, then inspect or report the caught condition. Treat sample code as a pattern to adapt to the runtime installed at your site, not as a substitute for checking the classes and handlers available in that environment.

A useful test normally checks four things: the operation enters the expected failure path, the condition has the intended type or identity, the message contains useful diagnostic information, and cleanup has taken place. Testing only the message is fragile because wording often changes during maintenance. Testing only the type can miss a serious regression in the details shown to an operator.

For example, a test for a lookup method could arrange a deliberately absent identifier, execute the method inside a handler, and record whether the expected condition was caught. If execution continues after the call without entering the handler, the test must fail explicitly. An exception test that passes when no exception is raised provides false confidence.

Build A Small Magik Test Harness

Keep exception tests independent from production data wherever possible. A temporary collection, an in-memory object, or a controlled fixture is preferable to a record selected from a shared Sydney or Melbourne database. Shared data can change between runs, producing a test that passes in the morning and fails after another developer has edited the same object.

A practical harness has a setup phase, one operation under test, an assertion phase, and cleanup. The setup should create the smallest state that triggers the condition. Cleanup belongs in a protection or finalisation path supported by your Magik conventions, so a failed assertion does not leave locks, temporary files, or open database handles behind.

An illustrative shape looks like this:

_method exception_test.test_missing_record()
  _local caught << _false
  _local condition

  _try
    _self.service.find_record("missing-test-id")
    _self.fail("Expected a missing-record condition")
  _when error
    caught << _true
    condition << error
  _endtry

  _self.assert(caught)
  _self.assert_expected_condition(condition)
  _self.assert_contains(condition.description, "missing")
_endmethod

The exact assertion methods and condition accessors will depend on the test framework used by the project. Some teams wrap these operations in a local test class; others call a Smallworld test facility from an Emacs-driven command file. The important design is that the handler captures the condition and the test fails when control reaches the next statement without an exception.

Use a unique fixture identifier rather than a familiar production identifier. Australian projects often support regional offices, council systems, utilities, or mining operations with separate environments and different data refresh schedules. A test named missing-test-id is easier to recognise in logs than a value copied from a real customer record.

Drive Tests From Emacs

The most efficient workflow is to run a focused test from Emacs while the Magik process remains visible in a comint buffer. Save the source, load or compile the changed methods, invoke the test entry point, and inspect the resulting output without leaving the editor. A failure should take you directly to the test or production method that raised the condition.

A Magik Emacs extension can make this smoother by supplying commands for loading buffers, navigating methods, folding long source files, and inspecting objects at the point of failure. Even without specialised automation, separate buffers for source, process output, and test results create a reliable rhythm: edit, reload, run, inspect, and repeat.

Test concern	What to verify	Useful Emacs view
Condition identity	The expected condition or error class was raised	Source and debugger buffer
Diagnostic message	The message names the invalid input or operation	comint output
Control flow	The handler stops or redirects execution correctly	Stepping or trace output
Cleanup	Locks, cursors, files, and temporary objects are released	Object inspector or log
Repeatability	The same test behaves consistently across runs	Test result buffer
Integration boundary	A database or service error is translated correctly	Call stack and source navigation

Run the smallest relevant test first, then run the surrounding suite. This matters when a failure occurs in Perth while the development team is working on eastern Australian time: a concise log and a reproducible command give another engineer something concrete to review without waiting for a shared interactive session. Record the Magik image, Smallworld version, and environment name when those details affect condition behaviour.

Emacs can also help separate a Magik exception from an editor or operating-system problem. If a method calls native Windows functionality, inspect the boundary carefully. A failure involving dynamic-library loading or a missing symbol may require a different diagnosis from a domain condition; a Windows API reference can help explain why a low-level lookup fails before the Magik handler receives control.

Inspect Conditions Without Hiding Bugs

A broad handler is useful during exploration but dangerous in a permanent test. Catching every error and marking the test as successful can conceal a spelling mistake, a null object, or a broken database connection. Narrow the handler to the expected condition where the runtime and project conventions allow it. If a broad _when error form is required, assert the condition immediately and re-raise unexpected cases.

Diagnostic text deserves deliberate assertions. Check stable fragments such as a field name, identifier, or operation, rather than comparing an entire sentence that may change with localisation or runtime updates. If a production method adds an error code, prefer that code as the stable contract and use the human-readable message for a secondary check.

The debugger is valuable when the condition is not the one expected. Inspect the call stack, receiver, local variables, and relevant collection contents before changing the test. Object inspection is especially helpful for distinguishing an empty collection from a collection containing an invalid object, two states that may produce similar-looking output in a log.

Do not disable all error reporting just to make a suite quiet. In a development image, preserve enough information to identify the first failing method. In a CI or overnight run, capture the condition class, message, stack information, and test name in a plain log. A short, searchable report is easier for a consulting team in Brisbane or Adelaide to use than a screenshot of a transient debugger window.

Cover Recovery And Operational Behaviour

An exception test should examine what happens after the failure, not merely prove that the failure occurred. If a method opens a transaction, the test should verify rollback or safe closure. If it acquires a lock, the next operation should demonstrate that the lock was released. If it updates a collection before failing, the test should confirm whether the update is intentionally retained or correctly reversed.

Add tests for boundary conditions that reflect actual Magik work: a missing attribute, an empty collection, a duplicate key, a stale database object, an unavailable service, and malformed configuration. Keep each test focused on one contract. A single test that prepares five unrelated faults is hard to diagnose and tends to become brittle.

Recovery behaviour should be tested separately from error reporting. One test can verify that the correct condition is raised; another can verify that a caller catches it and presents an operator-friendly response. This distinction is useful in field deployments where a GIS operator may need to retry an operation, while an unattended batch job may need to record the failure and continue with the next feature.

Timing and environment also deserve attention. Avoid tests that depend on the current date, local machine paths, a particular Windows account, or a service that is only available during business hours. For Australian teams supporting remote and FIFO operations, deterministic tests reduce the difference between a developer’s workstation, a shared integration server, and an overnight production-like run. Use a controlled clock, fixture directory, and stubbed service where the framework permits it.

When an exception test exposes a genuine defect, keep the failing test with the fix. It becomes executable documentation for the next developer who navigates the method in Emacs. Include the expected condition, the trigger data, and the recovery rule in the test name or nearby comment, then commit the source and any required fixture definitions together.

Run the focused exception tests from Emacs during daily development, and include the complete suite in the project’s release checks. HydePark Consulting can help Magik teams improve this workflow, review condition-handling conventions, and connect Emacs-based development with broader Smallworld support practices. Build a small, repeatable failure test today, keep its diagnostic output clear, and let each captured exception strengthen the reliability of the next Magik release.