Stimulus and StimulusReflex

OpenFoodNetwork is in the process of moving away from AngularJS, and move to using Stimulus and StimulusReflex to keep highly interactive pages.

Stimulus:

Handbook : https://stimulus.hotwired.dev/handbook/introduction

Stimulus is a JavaScript framework ... designed to enhance static or server-rendered HTML — the “HTML you already have” — by connecting JavaScript objects to elements on the page using simple annotations.

Our stimulus controllers live here : https://github.com/openfoodfoundation/openfoodnetwork/tree/master/app/webpacker/controllers

Testing

The documentation doesn't really cover testing, but this a good place to start: https://shime.sh/til/testing-stimulus

Otherwise, check our existing tests: https://github.com/openfoodfoundation/openfoodnetwork/tree/master/spec/javascripts/stimulus

To run tests : yarn jest

Test that include translation :

You can mock I18n object with the code below :

beforeEach(() => {
  // Add a mock I18n object to
  const mockedT = jest.fn()
  mockedT.mockImplementation((string) => (string))

  global.I18n =  {
    t: mockedT
  }
})

afterEach(() => {
  delete global.I18n
})

Note that call to I18n needs to made inside the controller.

Debugging

To debug Jest tests, you can add a debugger; statement in the code (similar to Rails binding.pry), and run with a debugger. I couldn't get the built in node inspect mode working, so use this method which loads the Chrome DevTools:

# First time install:
npm install -g ndb

# Then run prefixed with ndb:
npx ndb yarn jest spec/javascripts/stimulus/my_controller_test.js

StimulusReflex

Update 2024-04-04: We are considering alternatives for the SR stack, due to its inability to guarantee a response to requests made. Please discuss any work regarding StimulusReflex in #dev before starting.

---

Documentation : https://docs.stimulusreflex.com/

We extend the capabilities of both Rails and Stimulus by intercepting user interactions and passing them to Rails over real-time websockets. These interactions are processed by Reflex actions that change application state. The current page is quickly re-rendered and the changes are sent to the client using CableReady. The page is then morphed to reflect the new application state.

Same as for Stimulus, StimulusReflex javascript controllers live here : https://github.com/openfoodfoundation/openfoodnetwork/tree/master/app/webpacker/controllers

Rails controllers are called "reflexes" : https://github.com/openfoodfoundation/openfoodnetwork/tree/master/app/reflexes

Testing

Again there isn't much information about testing, but at least there are some docs (WIP): https://docs.stimulusreflex.com/appendices/testing

A first attempt at unit testing with podia/stimulus_reflex_testing can be found here: products_reflex_spec.rb

Feature testing may require special handling too. Here's an example special handling for the loading screen: https://github.com/openfoodfoundation/openfoodnetwork/blob/6c2f958b3fdb0a309117893489fb5c54a97f375c/spec/system/admin/products_v3/products_spec.rb#L553 (make sure to also check the current version in case it's been improved).

Examples

Pages using Stimulus or Reflex include:

• Bulk Edit Products admin interface

CableReady

wtf.. there's more.