Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library

    std.test.assertContains

    Checks that text contains a requested string.

    assertContains(text: string, needle: string) -> ()
    Module
    std.test
    Receiver
    Not applicable
    Minimum arity
    2
    Maximum arity
    2

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.test in language mode 5.21.

    The current compiler selects std/test.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Parameter constraints

    assertNe(actual, expected) returns unit when ordinary value equality says the operands differ. It performs no string conversion before comparison.

    The operands must have a common comparable type under the ordinary equality rules. Known noncomparable values produce TPZ5007 during checking. A comparison fault propagates with its own diagnostic.

    assertContains(text, needle) returns unit when the exact needle occurs as a contiguous substring. Matching is case sensitive and preserves Unicode spelling. An empty needle succeeds even when the text is empty.

    Arguments are evaluated once from left to right before testing the condition. Successful calls have no further side effects and print nothing.

    A false assertion raises TPZ4007 at the assertion call. It returns no value and stops the current test before the next statement. Earlier argument side effects remain visible. Test runner handling of later test cases follows the test execution contract.

    The inequality failure message uses the ordinary rendering of the shared value in this form.

    ```text assertNe failed: both values are {value} ```

    The containment failure message includes the original text and needle in this form.

    ```text assertContains failed: {text} does not contain {needle} ```

    These assertions add test failure reporting to ordinary equality and string containment. They do not define a separate comparison relation.

    Result

    The declared result type is ().

    Effects

    Failures

    Result and effects

    Link

    Return unit when text contains the exact needle. An empty needle succeeds. A missing needle raises TPZ4007 with both strings.

    Related entries

    Link

    std.test

    Assert inequality and text containment

    Link
    Ruletopaz.stdlib.contract.test-comparisons.rule

    Assert inequality and text containment

    assertNe(actual, expected) returns unit when ordinary value equality says the operands differ. It performs no string conversion before comparison.

    The operands must have a common comparable type under the ordinary equality rules. Known noncomparable values produce TPZ5007 during checking. A comparison fault propagates with its own diagnostic.

    assertContains(text, needle) returns unit when the exact needle occurs as a contiguous substring. Matching is case sensitive and preserves Unicode spelling. An empty needle succeeds even when the text is empty.

    Arguments are evaluated once from left to right before testing the condition. Successful calls have no further side effects and print nothing.

    A false assertion raises TPZ4007 at the assertion call. It returns no value and stops the current test before the next statement. Earlier argument side effects remain visible. Test runner handling of later test cases follows the test execution contract.

    The inequality failure message uses the ordinary rendering of the shared value in this form.

    ```text assertNe failed: both values are {value} ```

    The containment failure message includes the original text and needle in this form.

    ```text assertContains failed: {text} does not contain {needle} ```

    These assertions add test failure reporting to ordinary equality and string containment. They do not define a separate comparison relation.

    Why

    Tests should disagree with a program value only when the same ordinary comparison disagrees. Silent success keeps output useful, and immediate failure prevents a false premise from affecting later assertions.

    Source evidence

    Compare values and exact substrings

    Link
    main.tpzCompare values and exact substringsOpen in Playground
    1. import std.test
    2. import std.io
    3. test.assertNe([1, 2], [1, 3])
    4. let present: Option<int> = Some(1)
    5. let absent: Option<int> = None()
    6. test.assertNe(present, absent)
    7. test.assertContains("Topaz", "opa")
    8. test.assertContains("é", "é")
    9. test.assertContains("text", "")
    10. test.assertContains("", "")
    11. io.writeLine("comparisons passed")
    Expected outputexit 0
    comparisons passed
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. comparisons passed
    Source evidence

    Evaluate each operand once in source order

    Link
    main.tpzEvaluate each operand once in source orderOpen in Playground
    1. import std.test
    2. import std.io
    3. function operand(label: string, value: int) -> int {
    4. io.writeLine(label)
    5. return value
    6. }
    7. let result: () = test.assertNe(operand("actual", 3), operand("expected", 4))
    8. io.writeLine("{result}")
    Expected outputexit 0
    actual
    expected
    ()
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. actual
    2. expected
    3. ()
    Source evidence

    Stop after equal operands fail assertNe

    Link
    main.tpzStop after equal operands fail assertNeOpen in Playground
    1. import std.test
    2. import std.io
    3. function operand(label: string, value: int) -> int {
    4. io.writeLine(label)
    5. return value
    6. }
    7. test.assertNe(operand("actual", 7), operand("expected", 7))
    8. io.writeLine("after")
    Expected outputNonzero exit
    actual
    expected
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4007 stdlib-assert-ne-equal at main.tpz:9:1
    Expected stdout
    1. actual
    2. expected
    Source evidence

    Keep substring matching case sensitive

    Link
    main.tpzKeep substring matching case sensitiveOpen in Playground
    1. import std.test
    2. import std.io
    3. io.writeLine("before")
    4. test.assertContains("Topaz", "topaz")
    5. io.writeLine("after")
    Expected outputNonzero exit
    before
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4007 stdlib-assert-contains-case at main.tpz:5:1
    Expected stdout
    1. before
    Source evidence

    Keep composed and decomposed spellings distinct

    Link
    main.tpzKeep composed and decomposed spellings distinctOpen in Playground
    1. import std.test
    2. import std.io
    3. io.writeLine("before")
    4. test.assertContains("é", "é")
    5. io.writeLine("after")
    Expected outputNonzero exit
    before
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4007 stdlib-assert-contains-spelling at main.tpz:5:1
    Expected stdout
    1. before
    Source evidence

    Reject values that ordinary equality cannot compare

    Link
    main.tpzReject values that ordinary equality cannot compareOpen in Playground
    1. import std.test
    2. let value = () => 1
    3. test.assertNe(value, value)
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5007 stdlib-assert-ne-non-comparable at main.tpz:4:1
    Source evidence

    Accept exact substrings and an empty needle

    Link
    main.tpzAccept exact substrings and an empty needleOpen in Playground
    1. import std.test
    2. import std.io
    3. test.assertContains("Topaz", "opa")
    4. test.assertContains("é", "é")
    5. test.assertContains("text", "")
    6. test.assertContains("", "")
    7. io.writeLine("text contained")
    Expected outputexit 0
    text contained
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. text contained
    Source evidence

    Diagnostics

    Link

    Assertion failed

    Value is not comparable or keyable

    Menu

    Download