Documentation, learning material improvements

[danschultz]

Here are some ways that the documentation and learning material could be improved. Contributions and suggestions are appreciated.

• Wiki
  • [ ] API Overview. Document each of the transformers, and include marble diagrams
  • [ ] How do I? An FAQ with examples on how to do common scenarios in Frappe.
  • [ ] Unit testing reactive applications. Best practices and examples around testing reactive applications.
• Tutorials
  • [x] Auto complete
  • [x] Registration form
  • [ ] Mario!
  • [ ] Canvas drawing
  • [ ] Image slideshow
• Dart Docs
  • [ ] The docs lack information on when a transformed streams is closed

[Andersmholmgren]

I would add doc, examples and best practices around testing. I find that the trickiest part. I have lots of unit tests but they are brittle as they are full of timers as I couldn't find a reliable way to know when they should be complete

Plus tips for debugging. Another tough area.

[danschultz]

@Andersmholmgren those contributions would be amazing! I actually haven't come across any articles on unit testing reactive applications. This would be a great resource for RxJS and Bacon too.

[Unit tests] are full of timers as I couldn't find a reliable way to know when they should be complete

Are your tests hanging if you don't use a timer? You generally shouldn't need to use them. Of course you probably had to use them with previous versions of Frappe :).

In v0.4, I try to close all transformed streams when their source stream is done. So the use of timers shouldn't be necessary anymore, as long as you remember to close the source stream. If your tests are hanging, that might indicate a memory leak either in your app, or in Frappe.

[danschultz]

@Andersmholmgren there's also a helper function in Frappe to test streams. Maybe you'll find it useful for your app.

Future testStream(Stream stream, {behavior(), expectation(List values)})

• stream is the stream to test, usually created from a stream controller
• behavior is a block function that adds events into the stream controller(s). It can return an optional Future that will delay the call to expectation.
• expectation is a block to test the expected values. It's called after the future returned by behavior completes, and is passed a list of the transformed values that the stream produced.

[Andersmholmgren]

You just made my day. With a bit of luck I'll be able to have reliable, repeatable and fast unit tests for this layer. That would be truly awesome On Thu, 5 Mar 2015 at 8:53 am, Dan Schultz [email protected] wrote:

I've also created a helper function https://github.com/danschultz/frappe/blob/master/test/shared/util.dart#L7 in Frappe to test streams.

Future testStream(Stream stream, {behavior(), expectation(List values)})

• stream is the stream to test, usually created from a stream controller
• behavior is a block function that adds events into the stream controller(s). It can return an optional Future that will delay the call to expectation.
• expectation is block to test the expected values. It's called after the future returned by behavior completes, and is passed a list of the transformed values that the stream produced.

Maybe you'll find it useful for your app.

— Reply to this email directly or view it on GitHub https://github.com/danschultz/frappe/issues/37#issuecomment-77257772.