Repository Public License
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX OS Automation9// File : Packages/ORIXScheduler/Tests/ORIXSchedulerTests/FileWatcherAndTriggerTests.swift10// Description : Real FSEvents integration tests in a temp directory,11// trigger monitor tests (real file watcher into a real12// engine, system events through their handlers) and13// LaunchAgent plist validation with plutil.14// Module : ORIXSchedulerTests15// Repository : https://git.spboucher.ai/orix-automation16// Created : 2026-11-2117// Last Modified : 2026-11-2118//19// =============================================================================20// AUTHOR & PROFESSIONAL AFFILIATION21// =============================================================================22//23// Author : Simon-Pierre Boucher24// Position : Professor of Finance25// Institution : Université du Québec en Outaouais (UQO)26// Department : Département des sciences administratives27// Organization : SP Boucher28//29// Website : https://spboucher.ai30// Git : https://git.spboucher.ai31//32// =============================================================================33// OFFICIAL CONTACT DIRECTORY34// =============================================================================35//36// General : info@spboucher.ai37// Professional : contact@spboucher.ai38// Direct : simon@spboucher.ai39// Research : research@spboucher.ai40// Development : dev@spboucher.ai41// Support : support@spboucher.ai42// Security/Admin : admin@spboucher.ai43// Notifications : notifications@spboucher.ai44//45// Preferred Contact: support@spboucher.ai46//47// =============================================================================48// COPYRIGHT & INTELLECTUAL PROPERTY49// =============================================================================50//51// Copyright (c) 202652// Simon-Pierre Boucher53//54// All rights reserved where applicable.55//56// This file is governed by the applicable project license,57// copyright notices, institutional agreements and relevant law.58//59// Unless expressly authorized by the applicable license or60// rights holder, copying, redistribution, sublicensing,61// publication and commercial exploitation are not permitted.62//63// Existing third-party rights and notices remain unaffected.64//65// =============================================================================66// CONFIDENTIALITY & SECURITY67// =============================================================================68//69// Classification : Public70// Distribution : Public repository; use is governed by the project license71// Security Contact : admin@spboucher.ai72//73// Access to this source does not independently grant permission74// to redistribute or disclose confidential materials.75//76// Do not embed credentials, private keys, access tokens,77// certificates or confidential personal information.78//79// =============================================================================80// LICENSE & MAINTENANCE81// =============================================================================82//83// License : Proprietary, all rights reserved (see license file)84// License File : LICENSE85// Maintainer : Simon-Pierre Boucher86// Technical Contact: dev@spboucher.ai87//88// =============================================================================89// END OF SP BOUCHER SOURCE HEADER90// =============================================================================9192import Foundation93import Testing94import ORIXTestingSupport95@testable import ORIXScheduler9697/// Thread-safe collector.98final class Collector<T: Sendable>: @unchecked Sendable {99 private let lock = NSLock()100 private var _values: [T] = []101 func add(_ value: T) { lock.withLock { _values.append(value) } }102 var values: [T] { lock.withLock { _values } }103 func reset() { lock.withLock { _values = [] } }104}105106/// Writes without the temporary file an atomic write goes through, so exactly one path changes.107func writePlain(_ dir: TempDirectory, _ name: String, _ text: String) throws {108 let url = dir.file(name)109 try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)110 try text.write(to: url, atomically: false, encoding: .utf8)111}112113/// Polls until `condition` holds; returns false on timeout.114func eventually(timeout: Double = 10, _ condition: @Sendable () async -> Bool) async -> Bool {115 let deadline = Date().addingTimeInterval(timeout)116 while Date() < deadline {117 if await condition() { return true }118 try? await Task.sleep(nanoseconds: 25_000_000)119 }120 return await condition()121}122123@Suite("FileWatcher (integration: real FSEvents in a temp directory)", .serialized)124struct FileWatcherIntegrationTests {125 @Test func reportsCreateModifyAndDelete() async throws {126 let dir = try TempDirectory(prefix: "orix-fw")127 defer { dir.remove() }128 let events = Collector<FileWatcher.Event>()129 let watcher = try FileWatcher(path: dir.url.path, debounceSeconds: 0.1) { events.add($0) }130 try watcher.start()131 defer { watcher.stop() }132 #expect(watcher.isRunning && watcher.path == dir.url.path)133 let file = dir.file("notes.txt").path134135 try writePlain(dir, "notes.txt", "one")136 #expect(await eventually { events.values.contains { $0.paths == [file] } }, "create not reported: \(events.values)")137 events.reset()138139 let handle = try FileHandle(forWritingTo: URL(fileURLWithPath: file))140 try handle.seekToEnd()141 try handle.write(contentsOf: Data("two".utf8))142 try handle.close()143 #expect(await eventually { events.values.contains { $0.paths == [file] } }, "modify not reported: \(events.values)")144 events.reset()145146 try FileManager.default.removeItem(atPath: file)147 #expect(await eventually { events.values.contains { $0.paths == [file] } }, "delete not reported: \(events.values)")148 #expect(!FileManager.default.fileExists(atPath: file))149150 // After stop() nothing more is reported.151 watcher.stop()152 #expect(!watcher.isRunning)153 events.reset()154 try writePlain(dir, "late.txt", "x")155 try await Task.sleep(nanoseconds: 600_000_000)156 #expect(events.values.isEmpty)157 }158159 @Test func debounceCoalescesABurstIntoOneEvent() async throws {160 let dir = try TempDirectory(prefix: "orix-fw")161 defer { dir.remove() }162 let events = Collector<FileWatcher.Event>()163 let watcher = try FileWatcher(path: dir.url.path, debounceSeconds: 0.5) { events.add($0) }164 try watcher.start()165 defer { watcher.stop() }166 let started = Date()167 for i in 0..<25 {168 try writePlain(dir, "burst-\(String(format: "%02d", i)).txt", "payload \(i)")169 try await Task.sleep(nanoseconds: 20_000_000)170 }171 #expect(await eventually { !events.values.isEmpty })172 // Leave time for a (wrong) second event to show up.173 try await Task.sleep(nanoseconds: 1_200_000_000)174 let all = events.values175 #expect(all.count == 1, "expected one coalesced event, got \(all.count)")176 #expect(all.first?.paths.count == 25)177 #expect(all.first?.paths == all.first?.paths.sorted())178 // It came after the burst ended plus the quiet period, not during the burst.179 #expect((all.first?.date.timeIntervalSince(started) ?? 0) >= 0.9)180 }181182 @Test func globFilterKeepsOnlyMatchingNames() async throws {183 let dir = try TempDirectory(prefix: "orix-fw")184 defer { dir.remove() }185 try FileManager.default.createDirectory(at: dir.file("sub"), withIntermediateDirectories: true)186 let events = Collector<FileWatcher.Event>()187 let watcher = try FileWatcher(path: dir.url.path, recursive: true, glob: "*.pdf", debounceSeconds: 0.2) { events.add($0) }188 try watcher.start()189 defer { watcher.stop() }190 try writePlain(dir, "ignored.txt", "x")191 try writePlain(dir, "report.pdf", "%PDF")192 try writePlain(dir, "sub/nested.pdf", "%PDF")193 try writePlain(dir, "sub/ignored.csv", "a,b")194 let expected = [dir.file("report.pdf").path, dir.file("sub/nested.pdf").path]195 #expect(await eventually { Set(events.values.flatMap(\.paths)) == Set(expected) }, "\(events.values)")196 try await Task.sleep(nanoseconds: 500_000_000)197 #expect(Set(events.values.flatMap(\.paths)) == Set(expected))198 #expect(watcher.accepts(dir.file("a.pdf").path) && !watcher.accepts(dir.file("a.pdfx").path) && !watcher.accepts("/elsewhere/a.pdf"))199 }200201 @Test func nonRecursiveIgnoresSubdirectoriesAndPathGlobsMatchRelativePaths() async throws {202 let dir = try TempDirectory(prefix: "orix-fw")203 defer { dir.remove() }204 try FileManager.default.createDirectory(at: dir.file("sub"), withIntermediateDirectories: true)205 let flat = Collector<FileWatcher.Event>()206 let shallow = try FileWatcher(path: dir.url.path, recursive: false, debounceSeconds: 0.2) { flat.add($0) }207 let scoped = Collector<FileWatcher.Event>()208 let byPath = try FileWatcher(path: dir.url.path, recursive: true, glob: "sub/*.csv", debounceSeconds: 0.2) { scoped.add($0) }209 try shallow.start()210 try byPath.start()211 defer { shallow.stop(); byPath.stop() }212 try writePlain(dir, "sub/deep.csv", "a,b")213 try writePlain(dir, "top.csv", "a,b")214 #expect(await eventually { flat.values.flatMap(\.paths).contains(dir.file("top.csv").path) })215 #expect(await eventually { scoped.values.flatMap(\.paths) == [dir.file("sub/deep.csv").path] })216 try await Task.sleep(nanoseconds: 400_000_000)217 #expect(!flat.values.flatMap(\.paths).contains { $0.hasPrefix(dir.file("sub").path + "/") })218 #expect(scoped.values.flatMap(\.paths) == [dir.file("sub/deep.csv").path])219 }220221 @Test func watchingASingleFileIgnoresItsSiblings() async throws {222 let dir = try TempDirectory(prefix: "orix-fw")223 defer { dir.remove() }224 try writePlain(dir, "config.json", "{}")225 let events = Collector<FileWatcher.Event>()226 let watcher = try FileWatcher(path: dir.file("config.json").path, debounceSeconds: 0.1) { events.add($0) }227 try watcher.start()228 defer { watcher.stop() }229 try writePlain(dir, "other.json", "{}")230 try "{\"a\":1}".write(toFile: dir.file("config.json").path, atomically: false, encoding: .utf8)231 #expect(await eventually { !events.values.isEmpty })232 try await Task.sleep(nanoseconds: 300_000_000)233 #expect(Set(events.values.flatMap(\.paths)) == [dir.file("config.json").path])234 }235236 @Test func missingPathsAndDoubleStartsAreTypedErrors() throws {237 #expect(throws: FileWatcherError.pathNotFound("/nonexistent/orix-\(1)")) {238 _ = try FileWatcher(path: "/nonexistent/orix-\(1)") { _ in }239 }240 let dir = try TempDirectory(prefix: "orix-fw")241 defer { dir.remove() }242 let watcher = try FileWatcher(path: dir.url.path) { _ in }243 try watcher.start()244 #expect(throws: FileWatcherError.alreadyStarted) { try watcher.start() }245 watcher.stop()246 watcher.stop()247 try watcher.start() // restartable248 watcher.stop()249 }250}251252@Suite("TriggerMonitor (integration for file changes; unit for system events through their handlers)", .serialized)253struct TriggerMonitorTests {254 private func schedule(_ id: String, _ trigger: TriggerSpec, enabled: Bool = true, paused: Bool = false) -> Schedule {255 Schedule(id: id, workflowID: "wf-\(id)", name: id, trigger: trigger, enabled: enabled, paused: paused, concurrency: .queue)256 }257258 @Test func aRealFileChangeBecomesAQueueItemInTheEngine() async throws {259 let dir = try TempDirectory(prefix: "orix-tm")260 defer { dir.remove() }261 let store = InMemoryScheduleStore()262 let recorder = LaunchRecorder()263 let engine = SchedulerEngine(store: store, launcher: { await recorder.launch($0, $1) }, owner: "test",264 configuration: SchedulerConfiguration(observesSystemWake: false))265 let inbox = try await engine.save(schedule("inbox", .fileChange(path: dir.url.path, recursive: false, glob: "*.pdf", debounceSeconds: 0.2)))266 let monitor = TriggerMonitor(engine: engine, configuration: .init(observesSystem: false))267 monitor.update(schedules: [inbox])268 defer { monitor.stop() }269 #expect(monitor.fileWatcherCount == 1 && monitor.problems.isEmpty)270271 try writePlain(dir, "ignored.txt", "x")272 try writePlain(dir, "invoice.pdf", "%PDF")273 #expect(await eventually { (try? await engine.queue().count) == 1 })274 let item = try #require(try await engine.queue().first)275 #expect(item.scheduleID == "inbox" && item.status == .pending && item.reason == "file change: invoice.pdf")276 await engine.tick()277 await engine.settle()278 #expect(recorder.count == 1)279280 // Pausing the schedule removes the watcher; nothing is enqueued any more.281 var paused = inbox282 paused.paused = true283 monitor.update(schedules: [paused])284 #expect(monitor.fileWatcherCount == 0)285 try writePlain(dir, "second.pdf", "%PDF")286 try await Task.sleep(nanoseconds: 700_000_000)287 #expect(try await engine.queue().count == 1)288 }289290 @Test func aMissingWatchedPathIsReportedNotIgnored() {291 let events = Collector<TriggerEvent>()292 let monitor = TriggerMonitor(configuration: .init(observesSystem: false)) { events.add($0) }293 defer { monitor.stop() }294 monitor.update(schedules: [schedule("gone", .fileChange(path: "/nonexistent/orix-inbox", recursive: true, glob: nil, debounceSeconds: 1))])295 #expect(monitor.fileWatcherCount == 0)296 #expect(monitor.problems["gone"]?.contains("does not exist") == true)297 #expect(events.values.isEmpty)298 }299300 @Test func loginFiresOncePerSessionAndOnlyShortlyAfterLogin() {301 let login = utc("2026-06-01T12:00:00Z")302 func monitor(now: String, _ events: Collector<TriggerEvent>) -> TriggerMonitor {303 TriggerMonitor(configuration: .init(loginWindowSeconds: 600, loginDate: { login }, now: { utc(now) }, observesSystem: false)) { events.add($0) }304 }305 let schedules = [schedule("hello", .login), schedule("off", .login, enabled: false), schedule("cron", .cron(expression: "@daily", timezone: nil))]306307 let soon = Collector<TriggerEvent>()308 let m1 = monitor(now: "2026-06-01T12:02:00Z", soon)309 m1.update(schedules: schedules)310 m1.update(schedules: schedules) // a second reconcile does not fire again311 #expect(soon.values.map(\.scheduleID) == ["hello"])312 #expect(soon.values.first?.dedupKey == "hello@login-\(Int(login.timeIntervalSince1970))")313 #expect(soon.values.first?.kind == "login" && soon.values.first?.reason == "login: session started 120 s ago")314315 // A monitor that starts an hour after login (app relaunched) does not fire.316 let late = Collector<TriggerEvent>()317 monitor(now: "2026-06-01T13:00:00Z", late).update(schedules: schedules)318 #expect(late.values.isEmpty)319320 // Unknown login time: reported as a problem, nothing fired.321 let unknown = Collector<TriggerEvent>()322 let m3 = TriggerMonitor(configuration: .init(loginDate: { nil }, observesSystem: false)) { unknown.add($0) }323 m3.update(schedules: schedules)324 #expect(unknown.values.isEmpty && m3.problems["hello"] != nil)325 }326327 @Test func aRestartedAgentCannotFireLoginTwiceForOneSession() async throws {328 let login = utc("2026-06-01T12:00:00Z")329 let h = Harness(start: "2026-06-01T12:01:00Z")330 let hello = try await h.engine.save(schedule("hello", .login))331 for _ in 0..<2 { // two agent processes in the same login session332 let monitor = TriggerMonitor(engine: h.engine, configuration: .init(loginDate: { login }, now: { h.clock.now() }, observesSystem: false))333 monitor.update(schedules: [hello])334 _ = await eventually(timeout: 2) { await h.items().count >= 1 }335 try await Task.sleep(nanoseconds: 100_000_000)336 }337 #expect(await h.items().count == 1)338 }339340 @Test func appLaunchPowerAndNetworkFireOnTheRightTransitions() {341 let events = Collector<TriggerEvent>()342 let monitor = TriggerMonitor(configuration: .init(observesSystem: false)) { events.add($0) }343 defer { monitor.stop() }344 monitor.update(schedules: [345 schedule("safari", .appLaunch(bundleID: "com.apple.Safari")), schedule("power", .powerConnected),346 schedule("net", .networkAvailable), schedule("net-paused", .networkAvailable, paused: true),347 ])348 monitor.handleAppLaunch(bundleID: "com.apple.TextEdit")349 monitor.handleAppLaunch(bundleID: "com.apple.Safari")350 #expect(events.values.map(\.scheduleID) == ["safari"])351 #expect(events.values.first?.reason == "app launched: com.apple.Safari")352 events.reset()353354 monitor.handlePower(onAC: true) // initial state: already on AC, no edge355 monitor.handlePower(onAC: true)356 #expect(events.values.isEmpty)357 monitor.handlePower(onAC: false)358 monitor.handlePower(onAC: true) // battery → AC359 monitor.handlePower(onAC: true)360 #expect(events.values.map(\.kind) == ["powerConnected"])361 events.reset()362363 monitor.handleNetwork(satisfied: true) // initial state364 #expect(events.values.isEmpty)365 monitor.handleNetwork(satisfied: false)366 monitor.handleNetwork(satisfied: true)367 monitor.handleNetwork(satisfied: false)368 monitor.handleNetwork(satisfied: true)369 #expect(events.values.map(\.scheduleID) == ["net", "net"])370 }371372 @Test func systemFactsAreReadable() {373 // Real system calls: the values depend on the machine, their shape does not.374 let boot = TriggerMonitor.bootDate()375 #expect(boot != nil && boot! < Date() && boot! > utc("2020-01-01T00:00:00Z"))376 let login = TriggerMonitor.consoleLoginDate()377 #expect(login != nil && login! <= Date())378 _ = TriggerMonitor.isOnACPower()379 }380381 @Test func realSystemObserversInstallAndTearDown() async throws {382 // Installs the real NSWorkspace, IOKit and NWPathMonitor observers. No event is expected: this Mac's power and383 // network state do not change during the test, and at start the current state is not an edge.384 let events = Collector<TriggerEvent>()385 let monitor = TriggerMonitor { events.add($0) }386 monitor.update(schedules: [schedule("safari", .appLaunch(bundleID: "ai.orix.never-launched")), schedule("power", .powerConnected), schedule("net", .networkAvailable)])387 try await Task.sleep(nanoseconds: 500_000_000)388 monitor.update(schedules: [])389 monitor.stop()390 #expect(events.values.isEmpty)391 }392}393394@Suite("LaunchAgent plist (unit + plutil integration)")395struct LaunchAgentPlistTests {396 private func agent() -> LaunchAgentPlist.Configuration {397 .init(label: "ai.orix.automation.agent", bundleProgram: "Contents/MacOS/ORIXBackgroundAgent",398 programArguments: ["ORIXBackgroundAgent", "--scheduler"],399 standardOutPath: "/Users/Shared/orix-test/agent.out.log", standardErrorPath: "/Users/Shared/orix-test/agent.err.log",400 environment: ["ORIX_AGENT": "1"], throttleIntervalSeconds: 10, associatedBundleIdentifiers: ["ai.orix.automation"])401 }402403 @Test func generatesTheExpectedKeys() throws {404 let plist = try LaunchAgentPlist.propertyList(agent())405 #expect(plist["Label"] as? String == "ai.orix.automation.agent")406 #expect(plist["BundleProgram"] as? String == "Contents/MacOS/ORIXBackgroundAgent")407 #expect(plist["ProgramArguments"] as? [String] == ["ORIXBackgroundAgent", "--scheduler"])408 #expect(plist["RunAtLoad"] as? Bool == true)409 #expect(plist["KeepAlive"] as? [String: Bool] == ["SuccessfulExit": false])410 #expect(plist["ProcessType"] as? String == "Background")411 #expect(plist["StandardOutPath"] as? String == "/Users/Shared/orix-test/agent.out.log")412 #expect(plist["StandardErrorPath"] as? String == "/Users/Shared/orix-test/agent.err.log")413 #expect(plist["EnvironmentVariables"] as? [String: String] == ["ORIX_AGENT": "1"])414 #expect(plist["ThrottleInterval"] as? Int == 10)415 #expect(plist["AssociatedBundleIdentifiers"] as? [String] == ["ai.orix.automation"])416 #expect(LaunchAgentPlist.plistName(for: agent()) == "ai.orix.automation.agent.plist")417418 var minimal = LaunchAgentPlist.Configuration(label: "ai.orix.min", programArguments: ["/usr/bin/true"], runAtLoad: false, keepAliveOnFailure: false)419 minimal.processType = "Standard"420 let small = try LaunchAgentPlist.propertyList(minimal)421 #expect(Set(small.keys) == ["Label", "ProgramArguments", "RunAtLoad", "ProcessType"])422 #expect(small["RunAtLoad"] as? Bool == false)423 }424425 @Test func plutilAcceptsTheGeneratedFile() throws {426 let dir = try TempDirectory(prefix: "orix-plist")427 defer { dir.remove() }428 let url = dir.file(LaunchAgentPlist.plistName(for: agent()))429 try LaunchAgentPlist.write(agent(), to: url)430 let text = try String(contentsOf: url, encoding: .utf8)431 #expect(text.hasPrefix("<?xml") && text.contains("<key>SuccessfulExit</key>") && text.contains("<false/>"))432433 let process = Process()434 process.executableURL = URL(fileURLWithPath: "/usr/bin/plutil")435 process.arguments = ["-lint", url.path]436 process.environment = ["LC_ALL": "C"]437 let pipe = Pipe()438 process.standardOutput = pipe439 process.standardError = pipe440 try process.run()441 process.waitUntilExit()442 let output = String(decoding: pipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)443 #expect(process.terminationStatus == 0, "plutil: \(output)")444 #expect(output.contains("OK"))445 #expect(LaunchAgentPlist.problems(inPlistAt: url).isEmpty)446447 // Round trip through the system parser.448 let parsed = try PropertyListSerialization.propertyList(from: Data(contentsOf: url), options: [], format: nil) as? [String: Any]449 #expect(parsed?["Label"] as? String == "ai.orix.automation.agent")450 #expect((parsed?["KeepAlive"] as? [String: Any])?["SuccessfulExit"] as? Bool == false)451 }452453 @Test func invalidConfigurationsAreRefusedWithReasons() {454 var c = agent()455 c.label = "not a label"456 c.bundleProgram = "/abs/olute"457 c.processType = "Turbo"458 c.standardOutPath = "~/Library/Logs/agent.log"459 c.throttleIntervalSeconds = 0460 c.environment = ["BAD=KEY": "1"]461 let problems = LaunchAgentPlist.problems(c)462 #expect(problems.count == 6, "\(problems)")463 #expect(throws: LaunchAgentPlist.ValidationError.self) { try LaunchAgentPlist.xmlData(c) }464465 let relative = LaunchAgentPlist.Configuration(label: "ai.orix.x", programArguments: ["agent"])466 #expect(LaunchAgentPlist.problems(relative).contains { $0.contains("absolute path") })467 #expect(LaunchAgentPlist.problems(.init(label: "ai.orix.x", programArguments: [])).contains("programArguments is empty"))468 #expect(LaunchAgentPlist.problems(.init(label: "ai.orix.x", bundleProgram: "Contents/../../evil", programArguments: ["x"])).count == 1)469 }470471 @Test func existingFilesAreChecked() throws {472 let dir = try TempDirectory(prefix: "orix-plist")473 defer { dir.remove() }474 let wrongName = dir.file("other.plist")475 try LaunchAgentPlist.write(agent(), to: wrongName)476 #expect(LaunchAgentPlist.problems(inPlistAt: wrongName) == ["file name must be ai.orix.automation.agent.plist"])477 let garbage = try dir.write("ai.orix.garbage.plist", "not a plist")478 #expect(LaunchAgentPlist.problems(inPlistAt: garbage) == ["not a property list dictionary"])479 let always = dir.file("ai.orix.always.plist")480 try PropertyListSerialization.data(fromPropertyList: ["Label": "ai.orix.always", "KeepAlive": true], format: .xml, options: 0).write(to: always)481 #expect(LaunchAgentPlist.problems(inPlistAt: always).count == 2)482 #expect(LaunchAgentPlist.problems(inPlistAt: dir.file("missing.plist")).first?.hasPrefix("cannot read") == true)483 }484}485