My logging library documented LOG_LEVEL, LOG_FORMAT, LOG_TIMESTAMP, and LOG_COLOR. It also had a helper for reading those environment variables, with unit tests that called the helper directly.
The logger’s creation path didn’t call it. Setting a documented environment variable didn’t apply that setting to the logger.
The tests covered parsing. They missed the connection between parsing and the API users called.
A tested helper outside the active path
In the last 1.x release, a search for loadConfigFromEnvironment in the source found its definition but no call from createLogger().
That search was a useful clue, not proof that nobody could call the exported helper. External code could import it. The relevant problem was more specific: creating a logger didn’t load the environment configuration as documented.
The helper returned a partial configuration. A unit test could supply LOG_LEVEL=debug, call the helper, and assert that the returned level was correct.
A user didn’t take those steps. They set the variable and created a logger. Without a call that merged the parsed settings into the active configuration, the successful unit test said nothing about their result.
This is an easy gap to leave in wrapper code. The helper gets an isolated test because it’s convenient to exercise. The connection to the public entry point still needs coverage of its own.
Another configuration field had a similar problem. The public type accepted a transports array, while the Node implementation constructed its own transport list instead of using that field. Type checking accepted the option; it couldn’t establish that the runtime honored it.
Making the settings work changed existing behavior
The 2.0 release connected the environment settings to logger creation. It also made them take precedence over configuration passed to createLogger().
That precedence rule matters during an upgrade. A process can already contain one of these variables even if the previous logger ignored it. Once the variable becomes active, the same application code can produce different logs.
The release treated this as a breaking change and documented it. I think that was appropriate: the old behavior was wrong according to the docs, but it was still the behavior an existing installation had been running.
Boolean parsing changed too. The old helper recognized the literal string true; LOG_TIMESTAMP=1 produced false when parsed directly. The replacement accepted additional forms, including 1.
Activating the environment settings and changing accepted values are related changes, but they aren’t interchangeable. An upgrade note needs to explain both what is now read and how it is interpreted.
A documented feature doesn’t become harmless to activate just because it should have worked before.
Exercise the API the documentation describes
The small regression test I want starts where the user starts: set an environment variable, create the logger through its public API, and observe the resulting output.
It also needs to control the test environment and restore anything it changes. Otherwise, one configuration test can affect another.
The helper tests should stay. They can cover accepted values and invalid inputs without creating a logger for every case. A public-API test adds different evidence: the parsed setting reaches the behavior users see.
For configuration options, accepting a value is only part of the feature. The value has to make it through the application path where the documentation says it takes effect.
Sources
- The logan-logger-ts 2.0 commit — environment settings becoming active, precedence, and boolean parsing changes.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].