However the Lucee docs for writeLog were claiming that the file option was not implemented, and was also deprecated (this has since been rectified in the docs). It actually is implemented, but I was not so sure about the deprecation status. I asked and got no straight answer really. Anyway, the docs now say it's all good, so that's something.
Whilst this works, the log file is not managed by Lucee: it doesn't show up in Lucee Admin, so one cannot set things like log level / file size / file retention etc. This is fine for some situation, but was not fine for us. We need to be able to control the log level.
local.admin = new Administrator("web", server.system.environment.ADMINPASSWORD)
admin.updateLogSettings(
name = "AdamTest",
level = "ERROR",
appenderClass = "lucee.commons.io.log.log4j2.appender.ResourceAppender",
layoutClass = "lucee.commons.io.log.log4j2.layout.ClassicLayout",
appenderArgs = {maxfiles = 20,maxfilesize = 1073741824}
)
writeLog(log="AdamTest", type="ERROR", text="ERROR SHOULD BE LOGGED")
writeLog(log="AdamTest", type="INFO", text="INFO SHOULD NOT BE LOGGED")
And - hurrah - this does exactly what it looks like it does: all the settings are set correctly and respected. Most importantly for us is that the log level works: in this case logging an ERROR works, but any logs at level INFO are not logged. We have some debugging stuff we want to leave log entries in the codebase, but in general set the log to be ERROR so they don't log until we need to do some debugging.
I had to guess at the appenderArgs key values, but on a whim I assumed they'd be the same as the form fields in Lucee admin, and they kinda were:
A few days back I was chatting to someone about application-scope-usage, and how to trigger an event when any changes to the application scope took place. I mentioned that the application scope should never be accessed directly in one's application code, and it should be wrapped up in an adapter. And it's easy for one's adapter to trigger events if needs must. An implementation of the Observer Pattern would do the trick here.
I wanted to keep the article brief-ish and on-point, so just focused on one part of it. In this article I'll put that observer service to use in an application scope adapter.
Firstly I need a scope adapter. The interface to this will be the same for any scope, so I'm gonna keep the name generic.
Well: firstly I need some tests to clearly define how the thing should work:
describe("Tests for set method", () => {
it("sets a key's value in the scope", () => {
var scopeAdapter = new ScopeAdapter(local)
scopeAdapter.set("testVariable", "test value")
expect(local).toHaveKey("testVariable")
expect(local.testVariable).toBe("test value")
})
})
describe("Tests for get method", () => {
it("gets a value from the scope by its key", () => {
var scopeAdapter = new ScopeAdapter(local)
var testVariable = "test value"
var result = scopeAdapter.get("testVariable")
expect(result).toBe("test value")
})
})
And a very simple implementation:
component {
public function init(required struct scope) {
variables.scope = arguments.scope
}
public void function set(required string key, required any value) {
variables.scope[key] = value
}
public any function get(required string key) {
return variables.scope[key]
}
}
And that works. In real life before this was production-ready we'd probably want some error-handling around trying to get values that aren't set, and poss something to handle overwriting values etc. But for my purposes here: this will do.
When I first planned the code for this article in my head, the next step was gonna be to initialise the ScopeAdapter with an ObserverService object, and have it fire off some events on set. Then it occurred to me that this is breaking the Single Responsibility Principle a bit. It's not for the general ScopeAdapter to be doing anything other than being an adapter to a scope. So what I'm going to do is to use the Decorator Pattern: I'm going to create a decorator for a ScopeAdapter that is an ObservableScopeAdapter.
I need to back up slightly and do a slight refactor. If I'm using a decorator, then I need to be able to code to an interface, not to an implementation. I can't be having code that takes specifically a cfml.forBlog.applicationScopeAdapter.ScopeAdapter object; I need it to take an implementation of a cfml.forBlog.applicationScopeAdapter.ScopeAdapter interface. This is because when using a decorator, obviously it's no longer the same concrete implementation class. EG: if I have SomeService class, and it takes as one of its constructor parameters a ScopeAdapterobject, I can't then initialise it with an ObservableScopeAdapter. One might think this is solved by making ObservableScopeAdapter simply extend ScopeAdapter. This would work, but it's a bit of an anti-pattern, and I discuss this in "Decorator Pattern vs simple inheritance". Instead we provide an interface for both ObservableScopeAdapter and the current ScopeAdapter (which will need to be renamed) to implement, and we make our SomeService take one of those as its argument.
I'm going to rename ScopeAdapter to be GeneralScopeAdapter, and create an interface that it implements called ScopeAdapter. Yay for tests, as I am refactoring here, not just "changing shit". The only new code here is the interface:
interface {
public void function set(required string key, required any value);
public any function get(required string key);
}
Now we want our decorator. It will do two things:
Hand off any calls to methods in the ScopeAdapter interface to a full implementation of a ScopeAdapter it has been configured with
When set is called, it triggers an event that other code can have subscribed to.
"Hang on", you might say "isn't it doing two things, which is still a violation of the SRP?". Not really. It's only implementing the event trigger part. It's delegating the scope-adapting to its dependent GeneralScopeAdapter. Indeed it's not even implementing the event-triggering side of things. It's delegating that to the ObserverService. So the one thing the decorator is implementing is "making the scope access observable". Make sense?
Anyway here are some tests to set our expectations:
import cfml.forBlog.applicationScopeAdapter.GeneralScopeAdapter
import cfml.forBlog.applicationScopeAdapter.ObservableScopeAdapter
import cfml.forBlog.observerService.SimpleObserverService
component extends=Testbox.system.BaseSpec {
function run() {
describe("Tests for ObservableScopeAdapter", () => {
describe("Tests for set method", () => {
it("functions as a ScopeAdapter when setting a key's value in the scope", () => {
// same implementation as above
})
it("triggers an event when set is called, which receives the key/value of the set call", () => {
var eventLog = []
var localScopeAdapter = new GeneralScopeAdapter(local)
var observerService = new SimpleObserverService()
var observableScopeAdapter = new ObservableScopeAdapter(localScopeAdapter, observerService)
observerService.on("scope.set", (event) => {
eventLog.append(event)
})
observableScopeAdapter.set("testVariable", "test value")
expect(eventLog).toHaveLength(1)
expect(eventLog[1]).toBe({
name = "scope.set",
data = javaCast("null", ""),
detail = {key = "testVariable",value = "test value"}
})
})
})
describe("Tests for get method", () => {
it("functions as a ScopeAdapter when getting a value from the scope by its key", () => {
// same implementation as above
})
})
})
}
}
Notes:
I've changed the name of the ObserverService to be SimpleObserverService because I've extracted an interface for that too, and now that is called ObserverService. I didn't need to do this, but I figured it was more balanced, and "one should program to an interface", etc
Where I say same implementation as above, it's literally the same implementation as the earlier tests, because I want to test that the decorated implementation still behaves the same.
data is data passed along with the on call, which I am not using here.
I had actually neglected to add the feature of trigger to accept details (ie: data) at trigger-time in my initial implementation of BasicObserverService! So I had to add that functionality in. See below.
There's not much to the implementation:
import cfml.forBlog.applicationScopeAdapter.GeneralScopeAdapter
import cfml.forBlog.observerService.ObserverService
component implements=ScopeAdapter {
public function init(required GeneralScopeAdapter scopeAdapter, ObserverService observerService) {
variables.scopeAdapter = arguments.scopeAdaptervariables.observerService = arguments.observerService
}
public void function set(required string key, required any value) {
variables.observerService.trigger("scope.set", arguments)variables.scopeAdapter.set(argumentCollection=arguments)
}
public any function get(required string key) {
return variables.scopeAdapter.get(argumentCollection=arguments)
}
}
It implements the same interface as GeneralScopeAdapter, so it can be used anywhere that one of those is required.
It's initialised with an underlying GeneralScopeAdapter that does all the scope-adapting, as well as an ObserverService which does all the event handling.
get simply proxies to the underlying GeneralScopeAdapter
set does that too, but not before triggering an event that it's been called.
As I touched on above, I needed to add a feature to SimpleObservrService so that it passed detail data when triggering an event. Here's the test:
it("passes any extra details as part of the event", () => {
var observerService = new SimpleObserverService()
var eventResults = []
observerService.on("testEvent", (event) => {
eventResults.append([
message = "test event handler 1",
event = event
])
}, {key="value set in handler"})
observerService.trigger("testEvent", {
key = "value set by trigger"
})
expect(eventResults).toBe([[
message = "test event handler 1",
event = {
name = "testEvent",
data = {key = "value set in handler"},
detail = {key = "value set by trigger"}
}
]])
})
That's self-explanatory I think.
And implementation:
public boolean function trigger(required string event, struct detail={}) {
registerEvent(event)
return variables.eventRegistry[event].some((eventData) => eventData.handler({
name = event,
data = eventData?.data,detail = detail
}) == false)
}
This broke one other test, but in an expected way because it was testing what came back in the event struct, focusing on testing the data part, but it did not expect the new (empty) detail part of the data. All the other tests continued to pass, so I know this change has no unexpected side-effects.
That's it, all working. But how does one wire this into one's app? Well. Any place one currently accesses the application scope (remember the initial requirement was to trigger events when there were changes to the application scope) directly in the app needs to be swapped out for an instance of ObservableScopeAdapter that is adapting the application scope. This can be done easily enough with a DI framework: just inject it into whichever objects formerly accessed the application scope directly, and then use it. Secondly: wherever it is relevant to react to the "scope.set" event: pass in an instance of ObserverService, and attach an event handler to the "scope.set" event that does whatever one needs to. Obviously (?) it needs to be the same instance of ObserverService that the ObservableScopeAdapter is using. Again: super easy with your DI framework.
I realise this section is a bit like this:
But it's not really in scope here to explain how dependency injection works. You should already know.
The original question is begging slightly though. It presupposed the situation where there's application-scope access all over the place in an application. In a well-designed app, there simply shouldn't be. Everything ought to be managed by a DI container, and no actual objects ought to know what scope they are in, or care what scope their dependency objects are in. And data values that need to persist for the life of the application should just be in objects that persist for the life of the application, so this should not directly involve the application scope at all.
The same applies for any scope in your CFML code. The only scopes that should generally be relevant to your code are:
The variables scope of the CFC the code is in; reflecting the state of the object, or its dependencies, etc
The arguments scope of any argument values being passed into your function.
The local scope within your function.
One is possibly tied to some thread-specific scopes if using cfthread
That's it. If yer accessing any scopes other than those, you should be questioning the design of your application, I think.
A few days back I was chatting to someone about application-scope-usage, and how to trigger an event when any changes to the application scope took place. I mentioned that the application scope should never be accessed directly in one's application code, and it should be wrapped up in an adapter. And it's easy for one's adapter to trigger events if needs must. An implementation of the Observer Pattern would do the trick here.
Then it occurred to me that I have never actually implemented the Observer Pattern, and I thought I might give it a go.
I've read that Wiki article a few times, and know what it needs to do, but hadn't thought it through at all before. So I opened a file and settled in to work out what I'd need to do. Then I paused and went "Adam: tests. Don't let yerself down here". Grumble. But I reasoned that I didn't even know if I was gonna go anywhere with this code, so I decided to call it a spike (random code which will be thrown away, and no tests).
I decided to implement it as an ObserverService: an instance of it would be injected into other objects that needed to either attach a handler to an event, or trigger an event. Internally the service would have to maintain some data structure of events and handlers, and probably only needed a coupla methods. Following jQuery (my JS is very out of date, I admit this), I decided on on for the method to attach a handler to an event; and trigger to fire the event (and run the handlers). As I type this, I realise I'm already thinking of the bases for test cases. I shoulda just done the tests up front. Or at least made the test cases, eg:
describe("test for the on method", () => {
it("adds an event handler to an event", () => {
})
})
describe("test for the trigger method", () => {
it("runs all the event handlers for the event", () => {
})
})
Oh well.
Right so I spiked away, and it all came together rather more easily than I expected. Here's the first pass (untested):
component {
variables.eventRegistry = {}
public void function on(required string event, required function handler) {registerEvent(event)variables.eventRegistry[event].append(handler)}public boolean function trigger(required string event) {registerEvent(event)return variables.eventRegistry[event].some((handler) => handler())}
private void function registerEvent(required string event) {
if (!variables.eventRegistry.keyExists(event)) {
variables.eventRegistry[event] = []
}
}
}
That seems to have everything I need to start with:
I can attach a handler to an event.
I can trigger the event, causing the handlers to run in sequence.
If any handler returns false, stop calling handlers.
A bug that never would have cropped up had I done TDD properly.
Right so the way to check if this thing works is still via tests, so I knocked some tests together now. I'll just list the cases, as the implementations don't matter so much. I wrote all of these before running any of them (on purpose because I was being a dick, not cos it's good practice).
import cfml.forBlog.observerService.ObserverService
component extends=Testbox.system.BaseSpec {
function run() {
describe("Tests for ObserverService", () => {
describe("Tests for on method", () => {
it("registers an event handler", () => {
})
it("registers multiple event handlers", () => {
})
it("registers multiple handlers for multiple events", () => {
})
})
describe("tests for trigger method", () => {
it("triggers a registered event", () => {
})
it("does nothing when triggering an unregistered event", () => {
})
it("triggers event handlers until one returns false", () => {
})
})
})
}
}
And I triumphantly ran them, and then…
… I did not feel very triumphant any more. That was the result of every single test. So that's the bug. Did you spot it, or can you see it now?
The handlers I was attaching to the event didn't necessarily return true if they worked. Just "not erroring" is a good enough sign an event handler ran OK. EG:
Had I done TDD I'd've first done the minimum implementation without the "returning false from a handler terminates the handler loop" feature, then I would have added a test for the feature, and then my attention would have been focused on what I was actually doing, and I'd not have made such a stupid mistake.
Ah well.
After that first iteration, I realised I needed to also be able to pass data to the handler, so I did that too. Via TDD this time. This was the end result:
component {
variables.eventRegistry = {}
public void function on(required string event, required function handler, any data) {
registerEvent(event)
variables.eventRegistry[event].append({
handler = handler,
data = arguments?.data})
}
public boolean function trigger(required string event) {
registerEvent(event)
return variables.eventRegistry[event].some((eventData) => eventData.handler({name=event, data=eventData?.data}) == false)
}
private void function registerEvent(required string event) {
if (!variables.eventRegistry.keyExists(event)) {
variables.eventRegistry[event] = []
}
}
}
I'm pretty pleased with this simple little solution. It does what it needs to do, and is only ~700 bytes of code.
I'll get to why I'm creating this thing in a coupla days, showing how I'll use dependency injection to inject an instance of it into both publisher and subscribers of events, and how I solve that "firing an event every time the application scope is changed" challenge I mentioned in the beginning of this article.
I'm still working on the TinyTestFramework though: some things don't change.
My test file for this work, which is the framework and all its tests in one is getting a bit weighty: >1200 LOC, and I'm fiding it difficult to navigate about the place. Especially as I'm using trycf.com as my dev environment :-).
Using the technique I recently documented to execute code on trycf.com remotely ("Running CFML code on trycf.com via a remote HTTP request"), I've split-out the framework and the tests into different gists, and wrote a wee calling-harness to run them all… and for completeness on both ColdFusion 2021 and Lucee 5.
This way I can just have the new tests I am working on in front of me, and have all the rest of the tests running in a different trycf.com window.
It's not doing anything complicated: just some loops and some HTTP requests to get the code from GitHub, and send it to trycf.com; and then outputing the response:
I'm not doing it for these reasons. I mean… I am doing it, yes, obviously. But these are not my motivations:
To work out how to write a testing framework. This is not really that interesting to me. How to do it within a single expression (the whole thing is one struct literal)? Yes, interested in that. Def.
Because I think TestBox is doing anything wrong. It could not be further from the truth: I think TestBox is one of the best CFML projects out there. I am using it as inspiration, as I want code written in TinyTestFramework to be lift-and-shift-able into TestBox.
The reason why I am doing that project is n-fold:
I want to enable CFMLers to be able to run tests on trycf.com. Why:
I personally want to be able to present example code as tests to make it clear what I am trying to demonstrate (bug, idea, concept, help);
I want to encourage other CFMLers to think about asking question via TDD. Think through what they're asking, and think through how they derive their repro cases, showing us what they expect as an outcome. In a portable way.
As a practical exercise in TDDing some real-world code. I mean granted it's a slightly contrived situation - developing a test framework for trycf.com - but it's a real world project I am working on. And I am TDDing the whole lot.
For me personally: implementing non-trivial code in a restricted environment, and still come up with decent code. This project is a challenge for me.
A - largely in-vain, I suspect - attempt at intriguing some of the testing-nae-saying fuckwits out there to actually look at testing. Yeah good luck with that, Cameron.
If you are a CFML developer, you will be aware and likely use trycf.com. Whenever I have an issue with some CFML that needs to be demonstrated to someone else; eg: I'm asking for help on Slack or Stack Overflow, or demonstrating an answer to someone else's question: I create a portable / repeatable repro case on trycf.com. I use it to demonstrate bugs and behavioural differences to Adobe or Lucee when both vendors don't give the same result from the same code. I use it every day.
I believe trycf.com is the handiest resource available to CFML developers.
Until now Abram has done all the work to create and maintain trycf.com at his own expense, both financially and with his own time. I reached out to him a coupla days ago wanting to see if I could help-out financially, and he has set up a Patreon page for this very reason. His blurb is:
Go give him some money. If you're the purse-string holder at a company: consider giving him some money on behalf of your company too, to make yourselves better CFML Community participants.
Now even if the test fails, the afterEachHandler handler will still be run. And as I'm not catching the exception, it'll still do what it was supposed to. Rerunning the tests demonstrates this bug is fixed:
Demonstrating afterEach bug
Control
It is a passing test, to demonstrate excpected behaviour:
I also ran all the rest of the tests as well, and they all still pass, so I'm pretty confident my fix has had no repercussions.
I've got the same problem with aroundEach: the bit of the handler after the call to run the test was not being run, for the same reason we had with afterEach: a failing or erroring test throws an exception, and the exception is caught before the rest of the aroundEach handler can be run. This seems slightly trickier to handle, as the code to call the test is within the callback the tester provides:
aroundEach((test) => {
// top bit before calling the test. No problem with this
test()
// bottom bit. This is not getting run after a failed / erroring test
})
I can't expect the testing dev to stick handling of the test failure in there. I need to do this within the framework.
How to do this flummoxed me a bit, but I wrote some tests in the mean time to give my brain some time to think about things:
describe("Demonstrating aroundEach bug", () => {
aroundEach((test) => {
writeOutput("<br><br>Before the call to the test: this should be displayed<br>")
test()
writeOutput("<br>After the call to the test:This should be displayed<br><br>")
})
describe("Control", () => {
it("is a passing test, to demonstrate expected behaviour", () => {
expect(true).toBeTrue()
})
})
describe("Demonstrating bug", () => {
it("should display the 'bottom' message even if the test fails", () => {
expect(true).toBeFalse()
})
})
})
Results:
Demonstrating aroundEach bug
Control
It is a passing test, to demonstrate expected behaviour:
Before the call to the test: this should be displayed
After the call to the test: This should be displayed
OK
Demonstrating bug
It should display the 'bottom' message even if the test fails:
Before the call to the test: this should be displayed Failed
The culmination of that deocration code is how any aroundEach handler is called around the test implementation. Somehow I need to do the equivalent of that try / finally here. But it's not so straight forward as I basically need to prevent that call to implementation from erroring until after we bubble out of all the aroundEach handlers. Bear in mind there can be any number of aroundEach handlers to run: one for each level of describe in the tests:
describe("Test of a CFC", () => {
aroundEach((test) => {
// something before
test()
// something afterwards
})
describe("Test of a method", () => {
aroundEach((test) => {
// something before
test()
// something afterwards
})
describe("Test of a specific part of the method's behaviour", () => {
aroundEach((test) => {
// something before
test()
// something afterwards
})
it("will have all three of those `aroundEach` handlers run around it", () => {
// test stuff
})
})
})
})
OK so I need to put a try / catch around the call to implementation so i can stop it erroring-out too soon. That's easy enough:
I set a variable in the calling code either flagging the test worked, or if not: how it failed (or errored). The if it failed, I throw the exception I originally caught.
This works, and both those tests I wrote above, and all the rest of the test suite still passes too. Bug fixed.
I'm still thinking about this though. I feel I have nailed the red/green part of this process, but I still possibly have some refactoring to do. But obvs now I'm safe to do so because everything is tested. Well: except any other bugs I haven't noticed yet :-)
