package p.studio.api.automation; import p.studio.api.values.ValueMaps; import java.math.BigInteger; import java.nio.file.Path; import java.util.*; /** Isolated target and transcript contracts; independent of compiler ASTs and runtime wire codecs. */ public final class GuestTests { private GuestTests() {} public static final String PRODUCTION = "production"; public static final int SCHEMA_VERSION = 1; public record Target(String id, String entrypoint, List sourceRoots, List supportRoots, List exclusions, List cases, int logTag) { public Target { identifier(id); if (PRODUCTION.equals(id)) throw new IllegalArgumentException("production is reserved"); entrypoint = relative(entrypoint); sourceRoots = paths(sourceRoots); supportRoots = paths(supportRoots); exclusions = paths(exclusions); cases = List.copyOf(cases); cases.forEach(GuestTests::identifier); if (sourceRoots.isEmpty() || new HashSet<>(cases).size() != cases.size() || logTag < 0 || logTag > 65535) throw new IllegalArgumentException("Invalid test target"); if (exclusions.contains(entrypoint)) throw new IllegalArgumentException("Entrypoint cannot be excluded"); } } public record Catalog(int schemaVersion, List targets) { public Catalog { if (schemaVersion != SCHEMA_VERSION) throw new IllegalArgumentException("Unsupported testTargets schemaVersion"); targets = List.copyOf(targets); if (targets.stream().map(Target::id).distinct().count() != targets.size()) throw new IllegalArgumentException("Duplicate test target ID"); } public static Catalog empty() { return new Catalog(SCHEMA_VERSION, List.of()); } } public record Selection(String targetId) { public Selection { targetId = targetId == null ? PRODUCTION : targetId; identifier(targetId); } public boolean production() { return PRODUCTION.equals(targetId); } } public record BuildProvenance(String targetId, String buildId, String entrypoint, Map sourceSha256, Map assetSha256, Map dependencySha256, Map configuration, String revision) { public BuildProvenance { identifier(targetId); Objects.requireNonNull(buildId); Objects.requireNonNull(revision); sourceSha256 = Map.copyOf(sourceSha256); assetSha256 = Map.copyOf(assetSha256); dependencySha256 = Map.copyOf(dependencySha256); configuration = ValueMaps.object(configuration); } } public enum EventKind { suite_start, case_start, assertion, checkpoint, case_end, suite_end } public record Event(int schemaVersion, String suiteId, String caseId, String eventId, EventKind kind, Map payload) { public Event { if (schemaVersion != SCHEMA_VERSION) throw new IllegalArgumentException("Unsupported assertion schemaVersion"); identifier(suiteId); identifier(eventId); if (caseId != null) identifier(caseId); Objects.requireNonNull(kind); payload = ValueMaps.object(payload); } } public record LogEvent(BigInteger sequence, BigInteger frame, BigInteger timestampMs, String level, String source, Long appId, int tag, String message) { public LogEvent { uint64(sequence); uint64(frame); uint64(timestampMs); Objects.requireNonNull(level); Objects.requireNonNull(source); Objects.requireNonNull(message); if (tag < 0 || tag > 65535 || appId != null && (appId < 0 || appId > 0xffff_ffffL)) throw new IllegalArgumentException("Invalid log source/tag"); if (!Set.of("trace","debug","info","warn","error").contains(level) || !Set.of("pos","hub","vm","fs","app").contains(source) || source.equals("app") != (appId != null)) throw new IllegalArgumentException("Invalid typed log level/source"); } } public record LogPage(String sessionId, BigInteger logEpoch, List events, BigInteger oldestSequence, BigInteger newestSequence, BigInteger nextAfterSequence, boolean gap, boolean overflow) { public LogPage { Objects.requireNonNull(sessionId); if (sessionId.isBlank()) throw new IllegalArgumentException("Empty log session identity"); uint64(logEpoch); events = List.copyOf(events); if (events.size() > 1024) throw new IllegalArgumentException("Log page exceeds limit"); nullableUint64(oldestSequence); nullableUint64(newestSequence); nullableUint64(nextAfterSequence); if ((oldestSequence == null) != (newestSequence == null) || oldestSequence != null && oldestSequence.compareTo(newestSequence) > 0) throw new IllegalArgumentException("Invalid retention bounds"); BigInteger prior = null; for (var event : events) { if (oldestSequence == null || event.sequence().compareTo(oldestSequence) < 0 || event.sequence().compareTo(newestSequence) > 0 || prior != null && !event.sequence().equals(prior.add(BigInteger.ONE))) throw new IllegalArgumentException("Invalid event sequence"); prior = event.sequence(); } if (prior != null && !prior.equals(nextAfterSequence)) throw new IllegalArgumentException("Cursor must identify the final returned event"); } } public enum CaseState { passed, failed, not_run, infrastructure_failure } public enum Completion { running, completed, timed_out, cancelled, infrastructure_failure } public record Assertion(String name, String message, Object expected, Object actual, boolean passed, boolean expectedAvailable, boolean actualAvailable) { public Assertion(String name, String message, Object expected, Object actual, boolean passed) { this(name, message, expected, actual, passed, true, true); } public Assertion { Objects.requireNonNull(name); Objects.requireNonNull(message); var frozen = ValueMaps.fields("expected", expected, "actual", actual); expected = frozen.get("expected"); actual = frozen.get("actual"); } } public record CaseResult(String id, CaseState state, List assertions, List checkpointIds, boolean started, boolean completed) { public CaseResult(String id, CaseState state, List assertions, List checkpointIds) { this(id,state,assertions,checkpointIds,state!=CaseState.not_run,state==CaseState.passed||state==CaseState.failed); } public CaseResult { identifier(id); assertions = List.copyOf(assertions); checkpointIds = List.copyOf(checkpointIds); if (state == null && (!started || completed) || completed && !started) throw new IllegalArgumentException("Invalid case observation"); } } @FunctionalInterface public interface Decoder { Event decode(String message); } public record TranscriptEvent(LogEvent nativeEvent, Event event) { public TranscriptEvent { Objects.requireNonNull(nativeEvent); } } public record RunResult(String runId, String targetId, String buildId, String sessionId, String operationId, String clientRequestId, Completion completion, CaseState verdict, boolean suiteComplete, boolean lossDetected, List cases, List transcript, AutomationFailure failure, Map context) { public RunResult(String runId, String targetId, String buildId, String sessionId, String operationId, String clientRequestId, Completion completion, CaseState verdict, boolean suiteComplete, boolean lossDetected, List cases, List transcript, AutomationFailure failure) { this(runId,targetId,buildId,sessionId,operationId,clientRequestId,completion,verdict,suiteComplete,lossDetected,cases,transcript,failure,Map.of()); } public RunResult { Objects.requireNonNull(runId); identifier(targetId); Objects.requireNonNull(completion); Objects.requireNonNull(verdict); cases = List.copyOf(cases); transcript = List.copyOf(transcript); context = ValueMaps.object(context); if (verdict == CaseState.passed && (completion != Completion.completed || !suiteComplete || lossDetected || failure != null || cases.isEmpty() || cases.stream().anyMatch(c -> c.state() != CaseState.passed || !c.completed()) || cases.stream().flatMap(c -> c.assertions().stream()).noneMatch(Assertion::passed) || cases.stream().flatMap(c -> c.assertions().stream()).anyMatch(a -> !a.passed()))) throw new IllegalArgumentException("Incomplete, empty or failed run cannot pass"); } public RunResult withContext(Map additions) { var merged = new LinkedHashMap<>(context); merged.putAll(additions); return new RunResult(runId,targetId,buildId,sessionId,operationId,clientRequestId,completion,verdict,suiteComplete,lossDetected,cases,transcript,failure,merged); } } private static void uint64(BigInteger value) { if (value == null || value.signum() < 0 || value.bitLength() > 64) throw new IllegalArgumentException("Expected uint64"); } private static void nullableUint64(BigInteger value) { if (value != null) uint64(value); } private static void identifier(String value) { if (value == null || !value.matches("[A-Za-z0-9][A-Za-z0-9_.-]{0,127}")) throw new IllegalArgumentException("Invalid test identifier"); } private static String relative(String value) { Objects.requireNonNull(value); Path path = Path.of(value); if (value.isBlank() || path.isAbsolute() || path.normalize().startsWith("..") || !path.normalize().toString().equals(value) || value.equals(".") || value.contains("\\")) throw new IllegalArgumentException("Expected normalized project-relative path"); return value; } private static List paths(List values) { values = List.copyOf(values); values.forEach(GuestTests::relative); if (new HashSet<>(values).size() != values.size()) throw new IllegalArgumentException("Duplicate target path"); return values; } }