Test API
The scripts of a test workflow use the test API to prepare data, to drive the workflow under test, and to check the outcome:
var testApi = ctx.Use<ITestApi>();
The test API works in test workflows only. Use it together with the other APIs of the scripts, such as IDataApi, IRuleApi and IIdentityApi. Test a workflow and Test workflow navigation show the methods at work.
Check the outcome
| Method | What it does |
|---|---|
True(condition, reason) |
Fails the test when the condition is false, and stops it. |
False(condition, reason) |
Fails the test when the condition is true, and stops it. |
Check(condition, reason) |
Notes a failed check, and the test goes on. The test fails when it ends, and its error lists the reasons of all the failed checks. |
Use True and False for what the rest of the test depends on, for example that a record exists before you read its fields. Use Check for the other checks: one run then tells you about all of them.
testApi.True(project != null, "The project is saved");
testApi.Check(project.Get<string>("Title") == "Community garden", "The project has its title");
Keep values for the next steps
| Method | What it does |
|---|---|
Set(name, value) |
Keeps a value under a name, for the next activities of the test. A name can be set once. |
Replace(name, value) |
Changes the value kept under a name. |
Get<T>(name) |
The value kept under a name. T must be the type of the value, for example int for a value kept as int, not long. |
Get(name) |
The value kept under a name, as a DynamicDataObject. |
The names are not case-sensitive. Get fails for a name that was never set.
Make test data
| Method | What it does |
|---|---|
New<T>(name) |
A random value of type int, long, string, Guid, double, bool or DateTime. With a name, the value is kept under it. |
New(dataClass, name) |
A record of the data class with random values, in memory only. Foreign key, document and decimal attributes are empty. |
Create(dataClass, name) |
Saves a record of the data class with random values, and returns its ID. With a name, the ID is kept under it. |
Create(dataClass, data, name) |
Saves a record with these values, and returns its ID. |
CleanAll() |
Removes the records that Create saved, now. |
The name is optional in all of them.
var jobId = testApi.Create("DocsPlatJob", new { Name = "Nightly import", IsActive = true }, "job");
When the test ends, the records that Create saved are removed: they are marked as deleted. The records that the workflow under test saves stay, and so do the records that a script saves with IDataApi. Remove them at the end of the test, or with a teardown workflow (see Create a test).
Drive the workflow under test
| Method | What it does |
|---|---|
Submit(workflow, activity, data...) |
The data a user enters in a form of the workflow under test. The form uses it when the workflow gets to it. |
SubmitWhen(workflow, activity, () => data) |
The same, but the data is made when the workflow gets to the form, so it can use what the earlier activities did. |
NavigationOnly() |
Skips the scripts of the workflows the test starts: their forms, steps and rules work as usual. See Test workflow navigation. |
OnExecuting(workflow, activity, () => ...) |
Runs code right before an activity of the workflow under test runs. |
OnExecuted(workflow, activity, () => ...) |
Runs code right after an activity of the workflow under test ran. |
Set(workflow, variable, value) |
Sets a workflow variable of the workflow under test while it runs, in OnExecuting or OnExecuted. |
CreateDocumentUploadSession(documentId, workflow, activity, component, fileSize, fileName) |
Prepares a document for a file upload component of a form. Call it in OnExecuting of the form. |
SimulatePluginInvocation(plugin, method) |
Replaces the calls of a plugin method. See Replace a plugin call. |
The data of a form is one FormSubmittedDataObject for each data source the form saves:
| Data | For |
|---|---|
FormSubmittedDataObject.Create(dataSource, values) |
A new record. |
FormSubmittedDataObject.Create(dataSource, id, values) |
An existing record, by its ID. |
FormSubmittedDataObject.Create("WorkflowVariables", values) |
The workflow variables of the form. |
testApi.Submit("DocsWf Submit Application", "Submit form",
FormSubmittedDataObject.Create("DocsWfApplicant", applicantId, new { AgreeTerms = true }),
FormSubmittedDataObject.Create("WorkflowVariables", new { IsSkipReceipt = false }));
A form gets its fields from the data as a user would post them: a field of the form that the data leaves out is saved empty. A form without data is posted empty, and the workflow stops at it when it has required fields.
Look into the workflow under test
| Method | What it tells |
|---|---|
IsWorkflowCompleted(workflow) |
Whether the workflow ran to the end. |
IsActivityCompleted(workflow, activity) |
Whether the activity completed. |
IsActivityIncluded(workflow, activity) |
The result of the inclusion rule of the activity. |
IsActivityEditable(workflow, activity) |
The result of the editable rule of the activity. |
IsFormFieldVisible(workflow, activity, component), IsFormFieldEnabled, IsFormFieldRequired, IsFormFieldReadonly |
The state of a component of a form. |
GetFormState(workflow, activity) |
The state of all the components of a form, by component name: Visible, Enabled, Required and ReadOnly. |
Get<T>(workflow, variable), Get(workflow, variable) |
A workflow variable. The variable named after a data source holds the ID of the record the workflow saved in it. |
Ref(workflow, dataSource) |
The record the workflow saved in a data source. |
Path(workflow) |
The activities that ran, in their order. |
AssertPath(workflow, activities...) |
Fails the test, and stops it, when the activities that ran are not exactly these. The error shows both routes, and the rules of the activity where they part. |
AssertNotReached(workflow, activity) |
Fails the test, and stops it, when the activity ran. |
They know the workflows that the test started: the workflow under test, and the setup and teardown workflows. An unknown workflow, activity or component name makes them fail, and so does a variable that was never set. Names are case-sensitive.
var form = testApi.GetFormState("DocsWf Submit Application", "Submit form");
testApi.Check(form["AgreeTerms"].Visible, "The applicant sees the terms");
The user of the test
The scripts of a test run as the user of the test. IIdentityApi changes the claims of that user, for example to test a rule or a workflow that depends on the roles of the user:
| Method | What it does |
|---|---|
SetClaim(type, values...) |
Gives the user a claim, with one or more values. |
RemoveClaim(type) |
Removes a claim of the user. |
var identityApi = ctx.Use<IIdentityApi>();
identityApi.SetClaim("Roles", "Administrator");
The claims stay for the rest of the test, also in the workflow under test. Test a rule shows an example.
Add data with a test
A test with None as Resource Under Test has one script, Test. It is a handy way to run a script on demand, for example to add the sample data of a solution: run it with Run Test. Save such data with IDataApi, not with testApi.Create, which removes its records when the test ends:
var dataApi = ctx.Use<IDataApi>();
var testApi = ctx.Use<ITestApi>();
// The sample jobs, when they are missing
foreach (var name in new[] { "Nightly import", "Weekly report" })
{
if (!dataApi.Any("DocsPlatJob", FilterBuilder.Create().Eq("Name", name).Build()))
{
dataApi.Add("DocsPlatJob", new { Name = name, IsActive = true });
}
}
ctx.CommitChanges();
testApi.True(dataApi.Any("DocsPlatJob", FilterBuilder.Create().Eq("Name", "Weekly report").Build()), "The sample jobs are there");