Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

Testing and debugging

Atsurae watches your widgets folder. Within about a third of a second of saving any file in it, Atsurae:

  1. reads and checks the widget again
  2. reloads its fonts and images
  3. restarts its script
  4. redraws the desktop and every preview

So the fastest workflow is your editor on one side and Customize Widgets on the other.

Select your widget in Customize Widgets. Below the preview, Problems & Console lists:

  • Errors (red): the widget can’t be shown until they’re fixed. Its switch is disabled and its card shows the first error.
  • Warnings (orange): the widget works, but something is probably wrong, like a misspelled token or a missing font.
  • Console output from your script’s console.log and friends, with times.

The Problems & Console pane showing an unknown-token warning and console output

Cards in the Library show a badge with the number of problems; hover over it to read them.

Every message, with its fix, is listed in Errors and warnings.

Symptom Likely cause
The file isn’t valid JSON A missing or extra comma, a missing quote, or curly quotes (“ ”) from a word processor
A token shows nothing A typo (Atsurae warns: Unknown token), or data that isn’t there (no song playing, no battery)
{script.x} shows nothing The script hasn’t returned x, or it stopped with an error; check the console
Text is in the wrong font The family name doesn’t match; see the warning, and check Font Book for the exact name
The widget doesn’t appear at all It’s turned off, or the file isn’t directly in the widgets folder, or it doesn’t end in .json/.atsuraewidget
An image is missing Wrong path in src, or the widget isn’t a package
Elements overlap Offsets too small for the font sizes; see Layout

Print things. console.log accepts any values and prints objects as JSON:

function update(context) {
console.log("now:", context.now.toString(), "options:", context.options);
...
}

Read the error. When a script fails, Atsurae stops it and shows the error with a line number:

Script error: ReferenceError: Can’t find variable: greting (line 6)

Fix the file and save; the script starts again.

Guard against missing data. context.weather is null until the weather loads, and context.battery.level is null on desktop Macs. Code like context.weather.temperature throws then. Check first.

Test your logic in isolation. Copy your update function into Safari’s JavaScript console and call it with a fake context:

update({ now: new Date(2026, 11, 31, 23, 59), options: { name: "Sam" } })

That’s the easiest way to test dates you can’t wait for.

Before you share a widget, check it:

  • On different wallpapers: bright, dark and busy. See Readable on any wallpaper.
  • At different sizes: drag the Size slider from 0.25× to 3×.
  • In a different color: pick one in Customize Widgets.
  • With every option value.
  • Without data: no music playing, before the weather loads, on a Mac without a battery (if you can).
  • With long text: Wednesday, September, long song titles, and another language in System Settings ▸ General ▸ Language & Region.
  • In 12- and 24-hour time, if it shows times.
  • With no problems listed in Problems & Console.

Previews fill in example values for missing data. To see exactly what the desktop shows, turn the widget on, close the Atsurae window, and look at your desktop.