This PR introduces a new flavour of the builder API that's a bit more semantically structured and tightly integrated with test vector production.
It lives in package builders for now, and the central object is builders.Builder. There will be one entrypoint/constructor per test vector class. Right now, there's builders.MessageVector(metadata).
Building a message vector has three stages:
preconditions.
applies.
checks.
In the precondition stage, you initialize accounts, actors, etc.
In the applies stage, you accumulate the messages that will be applied.
In the checks stage, you perform a sanity check.
Calling v.CommitPreconditions() finalizes the precondition stage by taking a snapshot of the precondition state tree. The applies stage commences.
Calling v.CommitApplies() finalizes the applies stage by applying all messages and capturing the postconditions (state tree and receipts). The checks stage commences.
Calling v.Finished(io.Writer) declares this test vector as succeeded, and spits out the test vector JSON to the provided io.Writer (usually os.Stdout).
All throughout, you can perform assertions using the v.Assert object. It embeds the full testify toolkit, and enhances it with domain-specific asserters.
There are cases in the applies stage where certain the input of certain messages depends on the output of previous messages. For those cases, you can apply messages individually using v.Messages.ApplyOne(*ApplicableMessage) or v.Messages.ApplyN(*ApplicableMessage...). The following rules apply when using individual applications:
Messages must be applied in the order they are enrolled. Out-of-order applications will fail.
CommitApplies() will apply any trailing unapplied messages.
nonsense
commented
4 years ago
This PR introduces a new flavour of the builder API that's a bit more semantically structured and tightly integrated with test vector production.
It lives in package
buildersfor now, and the central object isbuilders.Builder. There will be one entrypoint/constructor per test vector class. Right now, there'sbuilders.MessageVector(metadata).Building a message vector has three stages:
In the precondition stage, you initialize accounts, actors, etc. In the applies stage, you accumulate the messages that will be applied. In the checks stage, you perform a sanity check.
Calling
v.CommitPreconditions()finalizes the precondition stage by taking a snapshot of the precondition state tree. The applies stage commences.Calling
v.CommitApplies()finalizes the applies stage by applying all messages and capturing the postconditions (state tree and receipts). The checks stage commences.Calling
v.Finished(io.Writer)declares this test vector as succeeded, and spits out the test vector JSON to the providedio.Writer(usuallyos.Stdout).All throughout, you can perform assertions using the
v.Assertobject. It embeds the full testify toolkit, and enhances it with domain-specific asserters.There are cases in the applies stage where certain the input of certain messages depends on the output of previous messages. For those cases, you can apply messages individually using
v.Messages.ApplyOne(*ApplicableMessage)orv.Messages.ApplyN(*ApplicableMessage...). The following rules apply when using individual applications:CommitApplies()will apply any trailing unapplied messages.This PR also migrates all suites to this new API.
TODO