jam-cloud/web/ai/specs/recurly-testing.md

We need to make sure that our Recurly based tracking and subscription management is rock solid.

First, do a comphrensive sweep of the code, and understand:

All use of the recurly client. Note where we make changes to a subscription from the user making payment input or subscription changes in the UI, focusing on the api_recurly_controller.rb in web. Note in ruby we should have what's called a HourlyJob (hourly_job.rb), and note that there is some processing related to recurly there; this HourlyJob is all important for synchronizing the state of our server to recurly, as subscirptions expire/renew etc, on Recurly's side.

Then look for all tests. Please literally list every test, and what it verifies. We should then focus on testing what the gap. In particular, we should test happy-path and non-happy-path recurly lifecycle stuff:

1. User enters payment and makes a non-free subscription choice (like silver, gold, platinum). Note that we immediately contact Recurly and attempt to trigger a payment of the user's card at that time. Does this work in a test? 1a. Note that the UI deliberately makes it so you can enter payment first, and then select a non-free subscription, or, do it in the opposite order. Both should trigger the same ultimate decision to attempt to charge the user and start their subscription
2. Then, we need to ensure that the recurly background job, in the hourly_job.rb, works. Meaning, if the state has not changed, that the job reflects that. If the user has cancelled their subscription, it should refelct that. If a month has gone by, and their payment no longer works, we should reflect that (this may require some clever TimeCop and recurly API usage to simulate passage-of-time tests).
3. We need to also be sure that the first-free month of a gold tier plan works as expected, with the passage of time. (may be tested already, but if not, we need to add tests).

In the end, we should have strong tests that use a browser for where it makes sense, and we should definitely have jobs that run the hourly job and change state on Recurly's side to provoke the various things a user's account may do (stop having valid payment, be canceled on the user's side, and so on).

1. First, let's scan the code and draw up a new folder called jam-cloud/docs/dev/subscriptions.md, and it should summarize how all of the code works now. And talk about how it's tested now.
2. We then create a jam-cloud/web/ai/tasks/test-subscriptions-plan.md, where we talk abuot all the tests we yet need to write.
3. Then we write all the tests needed to prove the feature works. Note: the feature works very well in production, however, that's using Rails 3 and we have migrated to Rails 8 on this branch, and we may have a regression or two. But Probably not, so if a test finds an error, we should first doubt the test, note the code. Or ask me to inspect the test failure and provide help.
4. Update docs/dev/subscriptions.md when done, to include references to the new tests. Finally, some tests should go in ruby/specs, some in web/specs. ruby tests models/clients etc, web tests controllers/UI and implicitely models too.