Reprocess elements after specific changes are made to them

CONTRIBUTING.md

@@ -22,6 +22,22 @@ To only run the JavaScript tests, open your console and run `yarn test` from the
 
 To only run the Ruby tests, open your console and run `rake test:helpers` from the project directory.
 
+### Integration tests
+
+Integration tests are run through `yarn` using [Playwright](https://github.com/microsoft/playwright) for browser testing. Browser and runtime configuration can be found in [`playwright.config.js`](./playwright.config.js).
+
+To begin testing, install the browser drivers:
+
+```bash
+yarn playwright install --with-deps
+```
+
+Then, run the tests:
+
+```bash
+yarn test:integration
+```
+
 ## Testing specific time zones
 
 Stubbing the browser's time zone is fragile. Although we have some automated tests for specific time zones, we also need to do some manual testing as follows:

lib/assets/javascripts/src/local-time/controller.coffee

@@ -1,14 +1,21 @@
 import LocalTime from "./local_time"
 import "./relative_time"
 import "./page_observer"
+import "./element_observations"
 
 {parseDate, strftime, getI18nValue, config} = LocalTime
 
 class LocalTime.Controller
-  SELECTOR = "time[data-local]:not([data-localized])"
+  SELECTOR = "time[data-local]"
+  NON_LOCALIZED_SELECTOR = "#{SELECTOR}:not([data-localized])"
 
   constructor: ->
-    @pageObserver = new LocalTime.PageObserver SELECTOR, @processElements
+    @observations = new LocalTime.ElementObservations(SELECTOR, @processElement)
+    @pageObserver = new LocalTime.PageObserver(
+      elementAddedSelector: NON_LOCALIZED_SELECTOR,
+      elementAddedCallback: @processElements,
+      elementRemovedSelector: SELECTOR,
+      elementRemovedCallback: @disconnectObserver)
 
   start: ->
     unless @started
@@ -21,11 +28,11 @@ class LocalTime.Controller
     if interval = config.timerInterval
       @timer ?= setInterval(@processElements, interval)
 
-  processElements: (elements = document.querySelectorAll(SELECTOR)) =>
+  processElements: (elements = document.querySelectorAll(NON_LOCALIZED_SELECTOR)) =>
     @processElement(element) for element in elements
     elements.length
 
-  processElement: (element) ->
+  processElement: (element) =>
     datetime = element.getAttribute("datetime")
     local = element.getAttribute("data-local")
     format = if config.useFormat24
@@ -57,6 +64,14 @@ class LocalTime.Controller
       when "weekday-or-date"
         relative(time).toWeekdayString() or relative(time).toDateString()
 
+    @connectObserver(element)
+
+  connectObserver: (element) =>
+    @observations.include(element)
+
+  disconnectObserver: (element) =>
+    @observations.disregard(element)
+
   markAsLocalized = (element) ->
     element.setAttribute("data-localized", "")
 

lib/assets/javascripts/src/local-time/element_observations.coffee

@@ -0,0 +1,52 @@
+import LocalTime from "./local_time"
+
+{elementMatchesSelector} = LocalTime
+
+class LocalTime.ElementObservations
+  OBSERVABLE_ATTRIBUTES = [ "datetime", "data-local", "data-format", "data-format24" ]
+
+  constructor: (@selector, @callback) ->
+    @elements = new Map()
+
+  include: (element) =>
+    unless @elements.get(element)
+      observer = @observe(element)
+      @register(element, observer)
+
+  disregard: (element) =>
+    if observer = @elements.get(element)?.observer
+      observer.disconnect()
+      @elements.delete(element)
+
+  observe: (element) =>
+    observer = new MutationObserver(@processMutations)
+    observer.observe(element, characterData: true, subtree: true, attributes: true, attributeFilter: OBSERVABLE_ATTRIBUTES)
+    observer
+
+  register: (element, observer) =>
+    @elements.set(element, { observer: observer, updates: -1 })
+    @incrementUpdates(element)
+
+  processMutations: (mutations) =>
+    for mutation in mutations
+      target = mutation.target
+
+      element = if target.nodeType is Node.TEXT_NODE
+        target.parentNode
+      else
+        target
+
+      if elementMatchesSelector(element, @selector)
+        @processLingeringElement(element)
+        break
+
+  processLingeringElement: (element) =>
+    @incrementUpdates(element)
+    @callback(element)
+
+  incrementUpdates: (element) =>
+    @elements.get(element).updates++
+    element.setAttribute("data-updates", @elements.get(element).updates)
+
+  size: ->
+    @elements.size

lib/assets/javascripts/src/local-time/page_observer.coffee

@@ -3,43 +3,52 @@ import LocalTime from "./local_time"
 {elementMatchesSelector} = LocalTime
 
 class LocalTime.PageObserver
-  constructor: (@selector, @callback) ->
+  constructor: ({
+    elementAddedSelector,
+    elementAddedCallback,
+    elementRemovedSelector,
+    elementRemovedCallback
+  }) ->
+    @elementAddedSelector = elementAddedSelector
+    @elementAddedCallback = elementAddedCallback
+    @elementRemovedSelector = elementRemovedSelector
+    @elementRemovedCallback = elementRemovedCallback
 
   start: ->
     unless @started
-      @observeWithMutationObserver() or @observeWithMutationEvent()
+      @observe()
       @started = true
 
-  observeWithMutationObserver: ->
-    if MutationObserver?
-      observer = new MutationObserver @processMutations
-      observer.observe(document.documentElement, childList: true, subtree: true)
-      true
-
-  observeWithMutationEvent: ->
-    addEventListener("DOMNodeInserted", @processInsertion, false)
-    true
-
-  findSignificantElements: (element) ->
-    elements = []
-    if element?.nodeType is Node.ELEMENT_NODE
-      elements.push(element) if elementMatchesSelector(element, @selector)
-      elements.push(element.querySelectorAll(@selector)...)
-    elements
+  observe: ->
+    observer = new MutationObserver @processMutations
+    observer.observe(document.documentElement, childList: true, subtree: true)
 
   processMutations: (mutations) =>
     elements = []
+
     for mutation in mutations
       switch mutation.type
         when "childList"
           for node in mutation.addedNodes
             elements.push(@findSignificantElements(node)...)
+
+          for node in mutation.removedNodes
+            if elementMatchesSelector(node, @elementRemovedSelector)
+              @elementRemovedCallback(node)
+
     @notify(elements)
 
+  findSignificantElements: (element) ->
+    elements = []
+    if element?.nodeType is Node.ELEMENT_NODE
+      elements.push(element) if elementMatchesSelector(element, @elementAddedSelector)
+      elements.push(element.querySelectorAll(@elementAddedSelector)...)
+    elements
+
   processInsertion: (event) =>
     elements = @findSignificantElements(event.target)
     @notify(elements)
 
   notify: (elements) ->
     if elements?.length
-      @callback?(elements)
+      @elementAddedCallback?(elements)

package.json

@@ -15,9 +15,12 @@
   },
   "homepage": "https://github.com/basecamp/local_time",
   "devDependencies": {
+    "@playwright/test": "^1.40.1",
     "@rollup/plugin-alias": "^5.0.0",
     "@rollup/plugin-node-resolve": "^15.1.0",
     "@rollup/plugin-terser": "^0.4.3",
+    "@web/test-runner-playwright": "^0.11.0",
+    "chai": "^4.3.10",
     "coffeescript": "^2.7.0",
     "express": "^4.18.2",
     "rollup": "^3.25.1",
@@ -27,6 +30,7 @@
     "start": "node test/javascripts/server.mjs",
     "build": "rollup -c",
     "watch": "rollup -wc",
-    "test": "yarn build && yarn start"
+    "test": "yarn build && yarn start",
+    "test:integration": "yarn build && playwright test"
   }
 }

playwright.config.js

@@ -0,0 +1,44 @@
+import { devices } from "@playwright/test"
+
+const config = {
+  projects: [
+    {
+      name: "chrome",
+      use: {
+        ...devices["Desktop Chrome"],
+        contextOptions: {
+          timeout: 5000
+        }
+      }
+    },
+    {
+      name: "firefox",
+      use: {
+        ...devices["Desktop Firefox"],
+        contextOptions: {
+          timeout: 5000
+        }
+      }
+    },
+    {
+      name: "webkit",
+      use: {
+        ...devices["Desktop Safari"],
+        contextOptions: {
+          timeout: 5000
+        }
+      }
+    }
+  ],
+  browserStartTimeout: 60000,
+  testDir: "./test/javascripts/",
+  testMatch: /integration\/.*_test\.js/,
+  webServer: {
+    command: "yarn start"
+  },
+  use: {
+    baseURL: "http://localhost:9000/"
+  }
+}
+
+export default config

test/javascripts/fixtures/integration_tests.html

@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<head>
+  <meta charset="utf-8">
+  <title>Integration Tests</title>
+  <script src="/current-build"></script>
+</head>
+<body>
+  <script>
+    LocalTime.start()
+
+    function simulateMorph() {
+      const textNode = document.getElementById("one").firstChild
+      textNode.nodeValue = "changed"
+    }
+
+    function changeDatetime() {
+      const element = document.getElementById("one")
+      element.setAttribute("datetime", "2015-12-04T14:00:00Z")
+    }
+
+    function changeToRelative() {
+      const element = document.getElementById("one")
+      element.setAttribute("data-local", "time-ago")
+    }
+
+    function changeFormat() {
+      const element = document.getElementById("one")
+      element.setAttribute("data-format", "%b %e")
+    }
+
+    function changeFormat24() {
+      LocalTime.config.useFormat24 = true
+      LocalTime.run()
+
+      const element = document.getElementById("one")
+      element.setAttribute("data-format24", "%B %e")
+    }
+
+    function changeFoo() {
+      const element = document.getElementById("one")
+      element.setAttribute("data-foo", "bar")
+    }
+
+    function reprocess() {
+      LocalTime.run()
+    }
+
+    function removeElement() {
+      const element = document.getElementById("one")
+      element.parentNode.removeChild(element)
+    }
+  </script>
+
+  <button id="morph" onclick="simulateMorph()">Morph</button>
+  <button id="change-datetime" onclick="changeDatetime()">Change Datetime</button>
+  <button id="change-relative" onclick="changeToRelative()">Change To Relative</button>
+  <button id="change-format" onclick="changeFormat()">Change Format</button>
+  <button id="change-format24" onclick="changeFormat24()">Change Format24</button>
+  <button id="change-foo" onclick="changeFoo()">Change Foo</button>
+
+  <button id="reprocess" onclick="reprocess()" style="background-color: darkseagreen;">Reprocess</button>
+  <button id="remove" onclick="removeElement()" style="background-color: firebrick; color: white;">Remove Element</button>
+
+  <br>
+
+  <time id="one" datetime="2024-12-04T14:00:00Z" data-format="%B %e, %Y" data-local="time"></time>
+</body>