Tables As Contracts⚓︎

A table contract is the agreement between the feature file and the test code. It says which labels are expected, which values are required, how cells should be understood, and what should happen when the table does not match.

Start with a table that looks obvious:

Given the users exist
  | name | age | role   | active |
  | Mira | 34  | admin  | yes    |
  | Leo  | 29  | editor | no     |

Humans can read this easily, but Python still needs the rules. Is role free text or one of a few allowed values? Is active optional? Is age really a number?

from talika import RowTable, boolean, choice, field


class UserTable(RowTable):
    name = field("name", required=True)
    age: int = field("age", required=True)
    role = field("role", parser=choice("admin", "editor", "viewer"))
    active = field(
        "active",
        parser=boolean(true_values=("yes",), false_values=("no",)),
        default=True,
    )

The contract is not only about conversion. It is a place to write down the meaning of the table.

users = UserTable.parse(datatable)

assert users[0].name == "Mira"
assert users[0].age == 34
assert users[0].role == "admin"
assert users[0].active is True

Labels and attributes⚓︎

The table label is the word the feature author sees. The Python attribute is the name test code uses after parsing.

That separation matters. Feature files can use product-facing language, while Python keeps normal names. A future table might say Full name, while the code still works with record.name.

A contract protects the author too⚓︎

If the authored labels no longer match the contract, the table should fail near the table, not later in the test setup.

The fields guide turns this agreement into code, starting with how to define a field contract.

| full name | age | role  | active |
| Mira      | 34  | admin | yes    |

This might be a mistake, or it might be a real vocabulary change. Either way, the contract forces the project to decide instead of letting the table quietly mean something different.