Skip to main content
Version: 0.4

Glossary

This page defines key terms used in ∗∗∗plain and serves as a quick reference while reading the ∗∗∗plain documentation.

Acceptance scenario is a scenario in the ***acceptance tests*** section of a test plain file. It covers an edge case of the functionality, or something learned from running the software in production: invalid parameters, wrong or missing authentication, missing data.

Acceptance test is generated test code that implements one acceptance scenario. It is rendered after the conformance tests of its functionality pass.

Concept is a domain entity, artifact, or shared reference that other requirements can point to. In ∗∗∗plain the concepts should be expressed using :Concept: notation.

Conformance scenario is a scenario in the ***conformance tests*** section of a test plain file. It is a core test of the functionality: a check that the functionality is properly implemented, on the main path, with valid parameters, the expected caller and the data present.

Conformance tests are generated from the conformance scenarios of a functionality, one test per scenario. They check whether the implementation matches the specification. A functionality is considered regenerated only when all of its test scenarios pass.

Definitions declare named concepts that the rest of the specification can refer to. Definitions are the shared domain model and vocabulary for the specification.

Durable system knowledge is everything about a software system that must survive so that the system can be safely rebuilt: the specifications that state what the software must do, the tests that any implementation must pass, and the decisions that define how the system is shaped. It is what a regenerative software system is regenerated from. In ∗∗∗plain it is captured in functional specs, test scenarios, and implementation reqs.

Func-id is the name of one functionality. It is written as a # func-id heading in the ***functional specs*** section: lowercase letters, digits and hyphens, unique in the module. Where the module is needed it is written as <module>:<func-id>. A func-id does not have to describe the functionality, and it stays the same for as long as the functionality exists.

Functional specs describe what the software must do. These are the behavioral requirements of the system.

Implementation reqs describe how the software should be implemented or constrained. These are non-functional requirements and implementation constraints such as language, framework, file naming, architecture, or coding rules.

Renderer is a tool that creates working software from a ∗∗∗plain specification.

Scenario is one test case written as text in a test plain file. It starts with a # scenario-id heading and continues with free text that says what is done and what result is expected. Scenarios are written by the developer or by a coding agent. The renderer never writes them.

Test plain file is a .plain file that holds the scenarios of one functionality. The frontmatter fields module and func_id bind it to that functionality. It has a ***conformance tests*** section and an ***acceptance tests*** section. By convention it lives at tests/<module>/<func-id>.plain.

Test reqs describe how conformance tests should be generated, structured, and executed. What the tests check comes from the scenarios, not from here. These are testing constraints for the spec-compliance test suite, not requirements for the implementation code itself.

Unit tests are automatically generated by the renderer to verify individual parts of the implementation code. These are the fine-grained tests for functions, classes, or modules.