Main Content

Linking to a Result File

You can link a requirement to a test result file that is in Microsoft® Excel® format using the Outgoing Links Editor and the API. The verification status in the Requirements Editor reflects the test results. These illustrations follow the workflow for including external test results in the requirement verification status. For more information, see Include Results from External Sources in Verification Status.

Open Example Files

Open the Integrating Results from an External Result File example.

openExample(['slrequirements/' ...
    'IntegratingResultsFromAnExternalResultFileExample'])
Open the counter_req requirement set in the Requirements Editor. This requirement set has child requirements that have requirement IDs and descriptions.

The Requirements Editor displays the counter_req requirement set, which has one parent requirement and three child requirements.

The external test results are contained in an Microsoft Excel file called results.xlsx. The verification status in Requirements Toolbox™ updates based on the values of the cells in the Microsoft Excel sheet. A unique ID in the Test column identifies each result in the Status column. The Test and Status labels are contained in a header row.

Three test results are shown in Microsoft Excel. The test name is shown in the left column and the test result is shown in the right. Two tests passed and one test failed.

Create and Register a Custom Document Interface

Before creating the links to the external result file, first create and register a custom document interface to enable linking to and getting results from the Microsoft Excel file.

  1. Open the myCustomDocInterface.m file by executing this code at the MATLAB® command line:

    open(fullfile(matlabroot,"toolbox","slrequirements","slrequirements","linktype_examples","myCustomDocInterface.m"))

  2. Replace the function name myCustomDocInterface with linktype_myexternalresults.

  3. Save a copy of the myCustomDocInterface.m in the current folder. In MATLAB, in the Editor tab, click Save > Save Copy As. Save the file as linktype_myexternalresults.m

  4. Set docInterface.Label to 'Excel Results'.

  5. Set docInterface.Extensions to {'.xlsx'}.

  6. Replace the existing GetResultFcn with this function:

    function result = GetResultFcn(link)
    testID = link.destination.id;
    if testID(1) == '@'
        testID(1) = [];
    end
    resultFile = link.destination.artifact;
    
    if ~isempty(resultFile) && isfile(resultFile)
        resultTable = readtable(resultFile);
        testRow = strcmp(resultTable.Test,testID);
        status = resultTable.Status(testRow);
    
        if status{1} == "passed"
            result.status = slreq.verification.Status.Pass;
        elseif status{1} == "failed"
            result.status = slreq.verification.Status.Fail;
        else
            result.status = slreq.verification.Status.Unknown;
        end
    else
        result.status = slreq.verification.Status.Unknown;
    end
    end
    For more information about GetResultFcn, see Define Custom Document Interface for Direct Linking to Requirements.

  7. Save linktype_myexternalresults.m.

  8. Register the custom document interface. At the command line, enter:

    rmi register linktype_myexternalresults

    Note

    If the command returns a warning, then you must unregister the link type and register it again. Unregister the link type by entering:

    rmi unregister linktype_myexternalresults

Link Requirements and External Test Results

You can create a link from a requirement to a test result for a test case from the external result file to confirm the requirement. You can create the link by using the Outgoing Links Editor, or by using the Requirements Toolbox API.

Create a Link by Using the Outgoing Links Editor

Create the link from a requirement to the external results file by using the Outgoing Links Editor:

  1. Open the Requirements Editor and, in the counter_req.slreqx requirement set, right-click the child requirement 1.3 and select Open Outgoing Links dialog.

  2. In the Outgoing Links Editor dialog box, in the Requirements tab, click New.

  3. Enter these details to establish the link:

    • Description:resultcounterSetsValue

    • Document type: Excel Results

    • Document: results.xlsx

    • Location: counterSetsValue

    The Outgoing Links Editor displays the new link with the previously described details.

  4. Click OK. The link is highlighted in the Links section of the Requirements Editor.

Create a Link by Using the API

Create the link from a requirement to the external results file by using the API:

  1. From the MATLAB command prompt, enter:

    externalSource.id = 'counterSetsValue';
    externalSource.artifact = 'results.xlsx';
    externalSource.domain = 'linktype_myexternalresults';

  2. Open the requirement set and find the requirement related to the link:

    reqSet = slreq.open('counter_req.slmx'); 
    requirement = find(reqSet, 'Type', 'Requirement', 'SID', 4);

  3. Create the link by entering:

    link = slreq.createLink(requirement, externalSource);
    This creates the link from the requirement with SID 4 to the result for the test case in the external result file called counterSetsValue. In the Requirements Editor, the link appears in the Links > Confirmed By section.

    Requirement that has a link in the Requirements Editor

View the Verification Status

Update the verification information for the counterSetsValue test case based on the Excel status log by updating the verification status for the requirement set.

You can update the verification status in the Requirements Editor by clicking Refresh . Ensure that Columns + > Verification Status is selected to view the verification status for entire requirement set.

Requirements Editor with an open requirement set that has three requirements. One requirement is verified.

The verification status shows that one of the three requirements is verified.

You can also update the verification status and fetch the current status by entering the following at the MATLAB command prompt:

updateVerificationStatus(reqSet)
status = getVerificationStatus(reqSet)

See Also

Apps

Functions

Related Examples

More About