Table of Contents

Stimulus:

Testing

Debugging

StimulusReflex

Testing
Upgrades

Examples
CableReady

OpenFoodNetwork is in the process of saying "Bye Bye Angular", and moving towards "Reactive Rails" to keep our focus on building with the Rails stack.

To support this, we are using Stimulus and ~~StimulusReflex~~ Turbo to maintain interactive pages where necessary.

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 StimulusReflex and CableReady, because they use WebSockets are are unable to guarantee a response to requests made. We have found that responses to important commands (eg print invoice) are intermittently lost, particularly if server is under load. Please discuss any work regarding this 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: 6c2f958b3f/spec/system/admin/products_v3/products_spec.rb (L553) (make sure to also check the current version in case it's been improved).

Upgrades

Dependabot will try bumping just one dependency, but there's actually four that need updating together (🙄). Make sure you wait at least a week after a release, because there's probably something wrong with it at first. Here's a shortcut to do it manually:

bundle update --conservative stimulus_reflex
bundle update --conservative cable_ready
yarn upgrade --latest stimulus_reflex
yarn upgrade --latest cable_ready

Examples

Pages using Stimulus or Reflex include:

Bulk Edit Products admin interface (Admin > Products)
Bulk Orders Management (Admin > Orders)

CableReady

wtf.. there's more.. eg in Bulk Orders Management page. Avoid using CableReady due to same issues as StimulusReflex.

Home

Development environment setup

Contributing

Development

Testing

Releasing

Specific features

Data and APIs

Instance-specific configuration

External services

Design