Workflows: Add a way to test workflow hibernation

[timfish]

When writing libraries or code to work with Cloudflare Workflows, we have to consider the fact that the state may be lost due to hibernation.

However, there is currently no (reasonable) way to test that our libraries or code do not violate the workflow rules and are not impacted by hibernation.

We could:

await step.sleep("Hopefully this hibernates", "1 hour");

But this is not really viable for tests!

How about something like this that only works with wrangler?

await step.hibernate();

[anonrig]

cc @cloudflare/workflows

[Caio-Nogueira]

we have to consider the fact that the state may be lost due to hibernation

I think this is an interesting approach. We're thinking about something that expands on this idea. Maybe this new testing API could work at the instance level - simulate an engine abort ("hibernation") after each step and expect the workflow to succeed. Another way would be running the same instance multiple times and expecting the execution flow to be deterministic within subsequent runs.

I think these alternatives could possibly cover the same cases and assert workflow rules more comprehensively. It also avoids leaking workflows internals as, in theory, users should not have to worry about hibernation in the first place.

[timfish]

It also avoids leaking workflows internals

Yep, makes sense!

At Sentry we are moving our Cloudflare tests to be more e2e to:

• Ensure our agent (as shipped) doesn't cause any runtime errors with it's proxying and wrapping
• Ensure we capture and report the expected events

It didn't seem possible to use @cloudflare/vitest-pool-workers to do this so we have a custom runner that runs wrangler directly with a seperate wrangler file for each test case.

Maybe this new testing API could work at the instance level - simulate an engine abort ("hibernation") after each step and expect the workflow to succeed

Yes, that would be perfect!

[kevinsimper]

I added some docs about hibernation and the inner workings of workflows, since that was also something I was looking at with loops and while loops for example cloudflare/cloudflare-docs#25781