Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Syntax and Test Cases

Writing Test Cases and Calling Keywords

Write Robot Framework test cases: call keywords with arguments, store results in variables, use named arguments, learn when tests fail and write Gherkin style.

A test case is a name plus a list of keyword calls. That is all. The art is in choosing keywords that read like a description of what you want to check. In this lesson you learn how a keyword call is written, how return values are stored, what makes a test pass, fail or skip, and the optional "Given-When-Then" style.

Anatomy of a test case

ROBOTFRAMEWORK
*** Test Cases ***
Basic arithmetic
    ${sum}=    Evaluate    2 + 3
    Should Be Equal As Integers    ${sum}    5
    Log    The sum is ${sum}

Strings behave
    ${upper}=    Convert To Upper Case    robot
    Should Be Equal    ${upper}    ROBOT
  • The test name is at the left edge and must be unique inside the file. It can contain spaces and most characters.
  • Each indented row is one keyword call: the keyword name, then its arguments.
  • ${sum}= before a keyword stores the keyword's return value in a variable. The = is optional but recommended because it makes the assignment clear.
  • Convert To Upper Case comes from the String library, so the file needs Library String in its Settings (the built-in library needs no import).

Keyword names ignore case, spaces and underscores: Should Be Equal, should be equal and should_be_equal are the same keyword. Choose the capitalized form with spaces so everyone reads it the same way.

Arguments

Arguments follow the keyword, separated by two or more spaces:

ROBOTFRAMEWORK
Should Be Equal    ${actual}    ${expected}
Log    Value is ${actual}    level=DEBUG
Should Be Equal    ${a}    ${b}    msg=The values should match    ignore_case=True

Arguments after the required ones can be given by name with name=value. Named arguments make a call self-explaining and let you skip optional arguments you do not need. Every argument is a string unless it comes from a variable holding another type, or the keyword converts it, so Should Be Equal 1 1.0 fails: the strings differ. Use Should Be Equal As Numbers (or ${1} for a real integer) when you mean numbers. Variables are covered fully in Scalar, List and Dictionary Variables.

Common BuiltIn keywords

These ship with Robot and need no import:

Keyword Purpose
Log, Log To Console, Log Many Write to the log or the terminal
Should Be Equal, Should Not Be Equal Compare values as given
Should Be Equal As Integers, ... As Numbers, ... As Strings Compare after conversion
Should Contain, Should Not Contain, Should Start With, Should End With Text and list membership
Should Be True, Should Not Be True A Python-style expression is true
Should Be Empty, Length Should Be, Should Match Regexp Sizes and patterns
Set Variable, Evaluate, Convert To Integer, Convert To String Make and convert values
Create List, Create Dictionary Build collections
Sleep, Fail, Skip, Pass Execution, No Operation, Comment Control and misc

Examples:

ROBOTFRAMEWORK
*** Test Cases ***
Collections and checks
    ${fruits}=    Create List    apple    banana    cherry
    Length Should Be    ${fruits}    3
    Should Contain    ${fruits}    banana
    ${n}=    Get Length    ${fruits}
    Should Be True    ${n} > 2
    Should Be Equal    ${fruits}[0]    apple

When does a test pass or fail?

A keyword fails when it raises an exception. The test then:

  1. Stops at that step; the remaining keywords are marked NOT RUN.
  2. Runs its teardown (see Tags, Setup and Teardown).
  3. Gets the status FAIL with the error message.

If every keyword finishes, the status is PASS. A third status, SKIP, is used when you call Skip, or when the test is skipped by --skip or by the special tag robot:skip. A test with no keywords at all fails, because an empty test is almost certainly a mistake.

To report your own failure use Fail message. To keep going after a failure inside one test, wrap a step in Run Keyword And Continue On Failure, or use Run Keyword And Ignore Error and look at the returned status:

ROBOTFRAMEWORK
*** Test Cases ***
Collect several problems
    Run Keyword And Continue On Failure    Should Be Equal    1    2
    Run Keyword And Continue On Failure    Should Be Equal    3    4
    Log    still running after two failures

The test is still FAIL in the end, with both error messages recorded.

Given / When / Then

You may start a step with Given, When, Then, And or But. Robot ignores that first word when it searches for the keyword, so these read like a specification:

ROBOTFRAMEWORK
*** Test Cases ***
Customer buys a book
    Given the shop has the book in stock
    When the customer orders one copy
    Then the stock is reduced to    4

The keywords the shop has the book in stock and so on are user keywords you write. See User Keywords.

Stand-in 1: a miniature test runner

The blocks here are not Robot Framework. This stand-in executes steps, supports ${var}= assignment and ${var} substitution, and stops at the first failure like a real test.

Python Stand-in: assignment and failure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: continue on failure

Run Keyword And Continue On Failure records the failure but runs the next step. The test is still FAIL in the end. The stand-in shows the difference between stopping and continuing.

Python Stand-in: stop vs continue

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Naming tests well

A test name is a sentence a stakeholder can read: Customer can reset a forgotten password beats Test 17. Describe behavior, not implementation. Keep each test independent so it can run alone, and keep one reason to fail per test.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does ${sum}= Evaluate 2 + 3 do?

    A variable followed by = before a keyword call receives the keyword's return value.
  2. 2. What happens to the remaining steps after a keyword fails in a test?

    Execution stops at the failing step; the test fails after its teardown runs.
  3. 3. Why does Should Be Equal 1 1.0 fail?

    Should Be Equal compares values as they are. Use Should Be Equal As Numbers for numeric comparison.
  4. 4. What does the word Given do at the start of a step?

    Given, When, Then, And and But are optional prefixes that Robot strips so tests can read like specifications.

Summary

  • A test case is a unique name followed by indented keyword calls.
  • Arguments are strings separated by two or more spaces; use name=value for named arguments.
  • ${var}= Keyword stores a return value; BuiltIn provides logging, comparison, conversion and collection keywords.
  • A failing keyword stops the test (rest NOT RUN); use Run Keyword And Continue On Failure to collect several failures.
  • Statuses are PASS, FAIL and SKIP; Given/When/Then prefixes are ignored.

Next: The Settings Section and Documentation