Search Results for

    Show / Hide Table of Contents

    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");
    
    In This Article
    Back to top Generated by DocFX