TestingInScarpe.md

Testing in Scarpe

Shoes-Spec DSL

Both Webview and Wasm display services for Scarpe implement the Shoes-Spec testing DSL, which is meant to be broadly portable. Niente implements it too, though the lack of an actual display service means it's of limited value for involved testing.

However, the Shoes-Spec DSL is a great base for writing more display-specific tests as well. In Webview, for instance, you can write something like "button.display.to_html" to get the display object and call .to_html on it. Shoes-Spec can't portably expose the full display service as Ruby objects -- it may not even be in this same process -- but different display services can provide additional functionality on top of portable Shoes-Spec.

It's fine to do this in the display service's own tests, or in gems or applications that depend specifically and directly on that display service. For more portable gems and applications, it's best to gate these tests behind a feature or extension so that it's clear to readers why it doesn't work with a different display service.

The Shoes-Spec Repo

There's a Shoes-Spec Repo for tests that can be written in a display-agnostic way. With the advent of Shoes features and extensions it's getting easier to write even tests that look at HTML in a more portable way. And many tests can simply be written portably and then tested across all display services.

Have a look in the "cases" directory in that repo for examples.

Unit Testing

You can unit test most things, especially if they're designed well. Scarpe-Components is a great area for unit testing -- most of it has to avoid the unportable APIs like Webview, so a lot of it is fairly pure logic. For instance, Calzini renders HTML but doesn't know what to do with it beyond that, so it's a great place to do straightforward unit testing.

A lot of code can be separated this way: hard-to-test infrastructure that needs integration testing, and easy-to-test logic that can be verified much more quickly with unit tests.

Mocking and Other Fast, Limited Testing

You can still find testing based on mocking, creating a drawable outside of a Shoes app, etc. in the various codebases. This is perfectly okay, and often runs very quickly, but it can be very fragile.

Outdated Methods

Local Scarpe-Webview has CatsCradle, a testing method based on using Fibers, so we get what looks like linear control flow, but actually it constantly stops to run the Webview event loop so that it can dispatch Javascript. This is much easier to use. It's also the basis of the Webview implementation of Shoes-Spec.

Scarpe-Wasm also has a local test implementation, but it's mostly testing the packaging code, not so much the actual GUI-app functionality.

We're working on Shoes-Spec, a testing API suitable for any display service. It currently runs just a few tests in both Scarpe-Webview and Scarpe-Wasm.

Scarpe-Webview had an older evented testing library. People couldn't use it. It didn't work well. It wasn't very stable. It's gone now.