Record Class TestDirective

java.lang.Object
java.lang.Record
org.ek9lang.compiler.directives.TestDirective
Record Components:
token - Source location of the directive
requirement - Optional requirement id this test anchors (null = unanchored)
group - Optional group name for sequential execution (null = parallel)
expectedExitCode - Optional exit code the program must end with (null = the default, 0)
lineNumber - The line number the directive applies to (the program declaration line)
All Implemented Interfaces:
Directive
public record TestDirective(IToken token, String requirement, String group, Integer expectedExitCode, int lineNumber) extends Record implements Directive
Test directive for marking programs as tests, optionally anchoring one to a requirement and declaring the exit code its program must end with. 
  @Test                                                 - parallel, unanchored, expects exit 0
  @Test: "database"                                     - execution group, unanchored
  @Test: "REQ:fraud-screening"                          - anchored, parallel
  @Test: "REQ:fraud-screening": "database"              - anchored and grouped
  @Test: "EXIT:3"                                       - passes only when the program exits 3
  @Test: "REQ:input-validation": "validation": "EXIT:3" - all three, in any order

The parts are told apart by their content, not their position

A part starting EXIT: is the expected exit code. Any other part with a colon is a requirement id (<PREFIX>:<slug>); an execution group may not contain one. That makes the classification total and order-independent, and it is what closes an otherwise silent failure: a mistyped prefix such as "RREQ:foo" or "EXT:3" would otherwise be a perfectly legal group name, dropping the anchor or the exit expectation with no diagnostic anywhere. Any colon-bearing part is therefore an anchor or exit attempt, and a malformed one is a compile error rather than a quiet degradation to a group.

Zero of the 622 @Test usages in the corpus contained a colon when the rule landed, so it was enforceable with no migration.

The fields also travel across phases on separate squirrelled keys. The group rides TEST_DIRECTIVE, which TestRunner reads as the sequential execution group; packing a requirement id or an exit code into it would silently reschedule every such test into a group named after it. The requirement rides REQUIREMENT_REF, the exit code TEST_EXIT_CODE.

  • Field Details

    • EXIT_PREFIX

      public static final String EXIT_PREFIX
      THE prefix of the expected-exit-code part, "EXIT:<n>". Shared with the editors that render the directive line, so the parser and the writers cannot disagree about its spelling.
      See Also:

    • MIN_EXIT_CODE

      public static final int MIN_EXIT_CODE
      The lowest exit code a test may expect.
      See Also:

    • MAX_EXIT_CODE

      public static final int MAX_EXIT_CODE
      The highest exit code a test may expect: a process exit status carries 8 bits.
      See Also:

  • Constructor Details

    • TestDirective

      public TestDirective(IToken token, String requirement, String group, Integer expectedExitCode, int lineNumber)
      Creates an instance of a TestDirective record class.
      Parameters:
      token - the value for the token record component
      requirement - the value for the requirement record component
      group - the value for the group record component
      expectedExitCode - the value for the expectedExitCode record component
      lineNumber - the value for the lineNumber record component

  • Method Details

    • type

      public DirectiveType type()
      Description copied from interface: Directive
      What s the type of the directive.
      Specified by:
      type in interface Directive

    • isForPhase

      public boolean isForPhase(CompilationPhase phase)
      Description copied from interface: Directive
      Is it for the particular compiler phase.
      Specified by:
      isForPhase in interface Directive

    • getAppliesToLineNumber

      public int getAppliesToLineNumber()
      Description copied from interface: Directive
      Which line number does this directive apply to.
      Specified by:
      getAppliesToLineNumber in interface Directive

    • getDirectiveToken

      public IToken getDirectiveToken()
      Description copied from interface: Directive
      Provide a token from the source, by default if not possible supply synthetic.
      Specified by:
      getDirectiveToken in interface Directive

    • hasGroup

      public boolean hasGroup()
      Check if this test has a group for sequential execution.

    • hasRequirement

      public boolean hasRequirement()
      Check if this test anchors a requirement.

      An unanchored test is entirely legitimate and carries no requirement by design - a unit test over a shared primitive is not "about" any one requirement.

    • hasExpectedExitCode

      public boolean hasExpectedExitCode()
      Check if this test declares the exit code its program must end with. Without one the expectation is 0.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • token

      public IToken token()
      Returns the value of the token record component.
      Returns:
      the value of the token record component

    • requirement

      public String requirement()
      Returns the value of the requirement record component.
      Returns:
      the value of the requirement record component

    • group

      public String group()
      Returns the value of the group record component.
      Returns:
      the value of the group record component

    • expectedExitCode

      public Integer expectedExitCode()
      Returns the value of the expectedExitCode record component.
      Returns:
      the value of the expectedExitCode record component

    • lineNumber

      public int lineNumber()
      Returns the value of the lineNumber record component.
      Returns:
      the value of the lineNumber record component