Improvements to test framework documentation

[MaryamZi]

Description

• https://ballerina.io/learn/test-ballerina-code/test-a-simple-function/

  • “The Ballerina language has a built-in robust test framework, which allows you to achieve multiple levels of the test pyramid including, unit testing, integration testing, and end-to-end testing. “
    • multiple levels or all levels?
    • if we claim this, shouldn’t the rest of the guide address each category at some point?
  • Add "support for" in "It provides support for assertions, data providers, mocking, and code coverage features, which enable the programmers to write comprehensive tests."
  • Remove empty {} after test:Config - applicable elsewhere too

• https://ballerina.io/learn/test-ballerina-code/write-tests/#define-a-test

  • before, after fields of the annotation - The default values are no longer nil. Now an optional field.
  • In the example, can’t we add at least a log in beforeFunc, afterFunc?
  • Remove unnecessary parenthesis - (int[][])
  • mapDataProvider - Avoid the unnecessary variable (and maybe make it an expression-bodied function)
  • Remove "to" in "to verify" of “The Ballerina test framework supports the following assertions, which help to verify the expected behavior of a piece of code.”

• https://ballerina.io/learn/test-ballerina-code/write-tests/#use-assertions

  • Mention somewhere what the “optional message” is for?

• https://ballerina.io/learn/test-ballerina-code/write-tests/#values-of-the-jsonrecordmap-type

  • “Values of the JSON/record/map type” -> JSON object, record, and map values
    • But JSON object IS map

• https://ballerina.io/learn/test-ballerina-code/configure-tests/#suite-level

  • {} not needed in the title
  • test:Config {} still has curly braces - check everywhere
  • “This can be used for cleaning up the test suite level aspects”. -> “This can be used for test suite level clean up.”

• https://ballerina.io/learn/test-ballerina-code/code-coverage-and-reporting/#generate-a-code-coverage-report

  • “The Ballerina test framework provides an option to analyze the code coverage of a standard Ballerina package.” - what’s a non-standard package?

• https://ballerina.io/learn/test-ballerina-code/define-data-driven-tests/

  • Feel like the flow can improve. E.g., the intro is “The Ballerina Test Framework allows you to specify a function that returns a set of data values as a data-provider.” and then in the next section only we explain data providers. Just including something like “ for data-driven tests.” may be better.
  • Use the term list instead of array and mapping instead of map since they all work with arrays and tuples and maps and records.
  • https://ballerina.io/learn/test-ballerina-code/define-data-driven-tests/#execute-specific-data-sets
    • Specific data sets or cases?
    • Package name is intg_tests in the first example
    • https://github.com/ballerina-platform/ballerina-lang/issues/42600

• https://ballerina.io/learn/test-ballerina-code/test-services-and-clients/#test-clients

  • The title is “Testing clients”, but is this section really that? Isn’t this more testing with clients?
  • “In cases where a fully fledged client is already defined for a particular service, you can make use of object mocking to mock the calls to the service and return curated responses to the client.” - IMO, the first sentence can be improved to make what’s being tested clearer

• https://ballerina.io/learn/test-ballerina-code/mocking/#stub-a-member-variable

  • In the test, assigning the mock object is not consistent with the previous pages

    E.g.,

    productClient = test:mock(ProductClient);
    test:prepare(productClient).getMember("productCode").thenReturn(mockProductCode);	
    

• https://ballerina.io/learn/test-ballerina-code/execute-tests/#re-run-failed-tests and https://ballerina.io/learn/test-ballerina-code/execute-tests/#run-selected-data-sets-in-data-driven-tests -”Run only the previously-failed cases in a data set.” commands are the same. Second one should change?

Related website/documentation area

Area/LearnPages