@griffin-app/griffin-ts 0.1.0

package/src/example-sequential.ts

@@ -0,0 +1,191 @@
+/**
+ * Example usage of the Sequential Test Builder
+ *
+ * This demonstrates the simplified createTestBuilder API for straightforward
+ * linear test flows. Use this when you don't need complex branching.
+ *
+ * For more complex graphs with parallel execution or conditional flows,
+ * see example.ts which uses createGraphBuilder.
+ */
+
+import {
+  GET,
+  POST,
+  createTestBuilder,
+  Json,
+  Frequency,
+  WaitDuration,
+  Assert,
+  target,
+} from "./index";
+
+// ============================================================================
+// Example 1: Simple health check with new assertion API
+// ============================================================================
+
+const healthCheck = createTestBuilder({
+  name: "health-check",
+  frequency: Frequency.every(1).minute(),
+})
+  .request("health", {
+    method: GET,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/health",
+  })
+  .assert((state) => [
+    Assert(state["health"].status).equals(200),
+    Assert(state["health"].body["status"]).equals("ok"),
+    Assert(state["health"].headers["content-type"]).contains(
+      "application/json",
+    ),
+  ])
+  .build();
+
+console.log("Health Check Plan:");
+console.log(JSON.stringify(healthCheck, null, 2));
+
+// ============================================================================
+// Example 2: Complex sequential flow with rich assertions
+// ============================================================================
+
+const userJourney = createTestBuilder({
+  name: "create-and-verify-user",
+  frequency: Frequency.every(5).minute(),
+})
+  .request("create_user", {
+    method: POST,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/api/v1/users",
+    body: {
+      name: "Test User",
+      email: "test@example.com",
+    },
+  })
+  .assert((state) => [
+    // Status code assertions
+    Assert(state["create_user"].status).equals(201),
+
+    // Body assertions with JSONPath
+    Assert(state["create_user"].body["data"]["id"]).not.isNull(),
+    Assert(state["create_user"].body["data"]["name"]).equals("Test User"),
+    Assert(state["create_user"].body["data"]["email"]).equals(
+      "test@example.com",
+    ),
+    Assert(state["create_user"].body["data"]["created_at"]).isDefined(),
+
+    // Header assertions
+    Assert(state["create_user"].headers["content-type"]).contains(
+      "application/json",
+    ),
+    Assert(state["create_user"].headers["location"]).startsWith(
+      "/api/v1/users/",
+    ),
+  ])
+  .wait("pause", WaitDuration.seconds(2))
+  .request("get_user", {
+    method: GET,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/api/v1/users/test@example.com",
+  })
+  .assert((state) => [
+    Assert(state["get_user"].status).equals(200),
+    Assert(state["get_user"].body["data"]["name"]).equals("Test User"),
+    Assert(state["get_user"].body["data"]["active"]).isTrue(),
+    Assert(state["get_user"].body["data"]["deleted"]).not.isTrue(),
+  ])
+  .build();
+
+console.log("\nUser Journey Plan:");
+console.log(JSON.stringify(userJourney, null, 2));
+
+// ============================================================================
+// Example 3: Advanced assertions with comparisons
+// ============================================================================
+
+const performanceCheck = createTestBuilder({
+  name: "performance-check",
+  frequency: Frequency.every(10).minute(),
+})
+  .request("api_call", {
+    method: GET,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/api/v1/metrics",
+  })
+  .assert((state) => [
+    // Numeric comparisons
+    Assert(state["api_call"].body["response_time_ms"]).lessThan(500),
+    Assert(state["api_call"].body["error_rate"]).lessThanOrEqual(0.01),
+    Assert(state["api_call"].body["success_count"]).greaterThan(0),
+    Assert(state["api_call"].body["memory_usage_mb"]).lessThan(1024),
+
+    // String assertions
+    Assert(state["api_call"].body["version"]).startsWith("v2."),
+    Assert(state["api_call"].body["deployment"]).not.equals(""),
+    Assert(state["api_call"].body["environment"]).contains("prod"),
+
+    // Array/collection assertions
+    Assert(state["api_call"].body["endpoints"]).not.isEmpty(),
+  ])
+  .build();
+
+console.log("\nPerformance Check Plan:");
+console.log(JSON.stringify(performanceCheck, null, 2));
+
+// ============================================================================
+// Example 4: Multi-step API test with state dependencies
+// ============================================================================
+
+const orderWorkflow = createTestBuilder({
+  name: "order-workflow",
+  frequency: Frequency.every(30).minute(),
+})
+  .request("create_order", {
+    method: POST,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/api/v1/orders",
+    body: {
+      items: [{ product_id: "ABC123", quantity: 2 }],
+      customer_email: "customer@example.com",
+    },
+  })
+  .assert((state) => [
+    Assert(state["create_order"].status).equals(201),
+    Assert(state["create_order"].body["order_id"]).isDefined(),
+    Assert(state["create_order"].body["status"]).equals("pending"),
+    Assert(state["create_order"].body["total"]).greaterThan(0),
+  ])
+  .request("confirm_order", {
+    method: POST,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/api/v1/orders/confirm",
+    body: {
+      order_id: "${create_order.body.order_id}", // Future: template interpolation
+    },
+  })
+  .assert((state) => [
+    Assert(state["confirm_order"].status).equals(200),
+    Assert(state["confirm_order"].body["status"]).equals("confirmed"),
+    Assert(state["confirm_order"].body["confirmed_at"]).not.isNull(),
+  ])
+  .wait("processing_time", WaitDuration.seconds(5))
+  .request("check_order", {
+    method: GET,
+    base: target("api-service"),
+    response_format: Json,
+    path: "/api/v1/orders/${create_order.body.order_id}",
+  })
+  .assert((state) => [
+    Assert(state["check_order"].status).equals(200),
+    Assert(state["check_order"].body["status"]).not.equals("pending"),
+    Assert(state["check_order"].body["processed"]).isTrue(),
+  ])
+  .build();
+
+console.log("\nOrder Workflow Plan:");
+console.log(JSON.stringify(orderWorkflow, null, 2));

package/src/example.ts

@@ -0,0 +1,55 @@
+/**
+ * Example usage of the griffin Test System DSL
+ *
+ * This file demonstrates how to create a test plan using the DSL.
+ * In practice, test files would be placed in __griffin__ subdirectories
+ * and discovered by the CLI tool.
+ */
+
+import {
+  GET,
+  POST,
+  createGraphBuilder,
+  Endpoint,
+  Wait,
+  Assertion,
+  Json,
+  START,
+  END,
+  Frequency,
+  WaitDuration,
+  target,
+} from "./index";
+
+const plan = createGraphBuilder({
+  name: "foo-bar-check",
+  frequency: Frequency.every(1).minute(),
+})
+  .addNode(
+    "create_foo",
+    Endpoint({
+      method: POST,
+      base: target("api-service"),
+      response_format: Json,
+      path: "/api/v1/foo",
+    }),
+  )
+  .addNode(
+    "get_foo",
+    Endpoint({
+      method: GET,
+      base: target("api-service"),
+      response_format: Json,
+      path: "/api/v1/foo",
+    }),
+  )
+  .addNode("first_wait", Wait(WaitDuration.minutes(1)))
+  // Note: Assertion nodes with the rich DSL are best used with the Sequential Builder
+  // For graph builder, assertions can be manually constructed with SerializedAssertion format
+  .addEdge(START, "create_foo")
+  .addEdge("create_foo", "get_foo")
+  .addEdge("get_foo", "first_wait")
+  .addEdge("first_wait", END)
+  .build();
+
+console.log(JSON.stringify(plan, null, 2));

package/src/frequency.ts

@@ -0,0 +1,38 @@
+import { Frequency as FrequencyType, FrequencyUnit } from "./schema";
+
+export class FrequencyBuilder {
+  private value: number;
+
+  constructor(value: number) {
+    this.value = value;
+  }
+
+  minute(): FrequencyType {
+    return { every: this.value, unit: FrequencyUnit.MINUTE };
+  }
+
+  minutes(): FrequencyType {
+    return { every: this.value, unit: FrequencyUnit.MINUTE };
+  }
+
+  hour(): FrequencyType {
+    return { every: this.value, unit: FrequencyUnit.HOUR };
+  }
+
+  hours(): FrequencyType {
+    return { every: this.value, unit: FrequencyUnit.HOUR };
+  }
+
+  day(): FrequencyType {
+    return { every: this.value, unit: FrequencyUnit.DAY };
+  }
+
+  days(): FrequencyType {
+    return { every: this.value, unit: FrequencyUnit.DAY };
+  }
+}
+
+// Export builder as Frequency for convenience
+export const Frequency = {
+  every: (value: number) => new FrequencyBuilder(value),
+};

package/src/http-methods.ts

@@ -0,0 +1,5 @@
+export const GET = "GET" as const;
+export const POST = "POST" as const;
+export const PUT = "PUT" as const;
+export const DELETE = "DELETE" as const;
+export const PATCH = "PATCH" as const;

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Griffin DSL - Top-level exports for building API tests.
+ *
+ * Import schema values from "griffin/schema"
+ * Import schema-derived types from "griffin/types"
+ */
+
+// ============================================================================
+// DSL Builders
+// ============================================================================
+
+export { createGraphBuilder } from "./builder";
+export type { TestBuilder } from "./builder";
+
+export { createTestBuilder } from "./sequential-builder";
+export type {
+  SequentialTestBuilder,
+  AssertionCallback,
+} from "./sequential-builder";
+
+// ============================================================================
+// DSL Node Factories
+// ============================================================================
+
+export { Endpoint, Wait, Assertion } from "./builder";
+export type {
+  EndpointConfig,
+  WaitDuration as WaitDurationType,
+} from "./builder";
+
+// ============================================================================
+// DSL Helpers
+// ============================================================================
+
+export { Frequency } from "./frequency";
+export { WaitDuration } from "./wait";
+export { target, isTargetRef } from "./target";
+export { secret, isSecretRef } from "./secrets";
+export type { SecretRefData, SecretOptions } from "./secrets";
+
+// ============================================================================
+// DSL Constants
+// ============================================================================
+
+export { START, END } from "./constants";
+export type { START as StartType, END as EndType } from "./constants";
+
+export { GET, POST, PUT, DELETE, PATCH } from "./http-methods";
+export { Json, Xml, Text } from "./response-formats";
+
+// ============================================================================
+// Assertion DSL
+// ============================================================================
+
+export {
+  Assert,
+  AssertBuilder,
+  UnaryPredicate,
+  BinaryPredicateOperator,
+  createStateProxy,
+} from "./assertions";
+
+export type {
+  SerializedAssertion,
+  PathDescriptor,
+  BinaryPredicate,
+  StateProxy,
+  NodeResultProxy,
+  NestedProxy,
+} from "./assertions";

package/src/response-formats.ts

@@ -0,0 +1,3 @@
+export const Json = "JSON" as const;
+export const Xml = "XML" as const;
+export const Text = "TEXT" as const;

package/src/schema-exports.ts

@@ -0,0 +1,43 @@
+/**
+ * TypeBox schemas and enums for griffin test plans.
+ * Import from "griffin/schema" to access validation schemas.
+ */
+
+export {
+  // Schema values
+  SecretRefDataSchema,
+  SecretRefSchema,
+  SecretOrStringSchema,
+  ResponseFormatSchema,
+  HttpMethodSchema,
+  TargetRefSchema,
+  EndpointSchema,
+  FrequencySchema,
+  WaitSchema,
+  JSONPathSchema,
+  XMLPathSchema,
+  TextPathSchema,
+  UnaryPredicateSchema,
+  BinaryPredicateOperatorSchema,
+  BinaryPredicateSchema,
+  JSONAssertionSchema,
+  XMLAssertionSchema,
+  TextAssertionSchema,
+  AssertionSchema,
+  AssertionsSchema,
+  NodeTypeSchema,
+  NodeSchema,
+  EdgeSchema,
+  TestPlanV1Schema,
+
+  // Enums (runtime values)
+  FrequencyUnit,
+  ResponseFormat,
+  HttpMethod,
+  NodeType,
+  UnaryPredicate,
+  BinaryPredicateOperator,
+
+  // Constants
+  TEST_PLAN_VERSION,
+} from "./schema.js";

package/src/schema.ts

@@ -0,0 +1,289 @@
+import { Type, type Static, type TSchema } from "typebox";
+
+export const TEST_PLAN_VERSION = "1.0";
+
+// Secret reference schema for values that may contain secrets
+export const SecretRefDataSchema = Type.Object({
+  provider: Type.String(),
+  ref: Type.String(),
+  version: Type.Optional(Type.String()),
+  field: Type.Optional(Type.String()),
+});
+
+export const SecretRefSchema = Type.Object({
+  $secret: SecretRefDataSchema,
+});
+
+// Union type for values that can be either a literal or a secret reference
+export const SecretOrStringSchema = Type.Union([
+  Type.String(),
+  SecretRefSchema,
+]);
+
+export enum FrequencyUnit {
+  MINUTE = "MINUTE",
+  HOUR = "HOUR",
+  DAY = "DAY",
+}
+
+export enum ResponseFormat {
+  JSON = "JSON",
+  XML = "XML",
+  TEXT = "TEXT",
+}
+
+export enum HttpMethod {
+  GET = "GET",
+  POST = "POST",
+  PUT = "PUT",
+  DELETE = "DELETE",
+  PATCH = "PATCH",
+  HEAD = "HEAD",
+  OPTIONS = "OPTIONS",
+  CONNECT = "CONNECT",
+  TRACE = "TRACE",
+}
+export enum NodeType {
+  ENDPOINT = "ENDPOINT",
+  WAIT = "WAIT",
+  ASSERTION = "ASSERTION",
+}
+export const ResponseFormatSchema = Type.Union(
+  [
+    Type.Literal(ResponseFormat.JSON),
+    Type.Literal(ResponseFormat.XML),
+    Type.Literal(ResponseFormat.TEXT),
+  ],
+  { $id: "ResponseFormat" },
+);
+
+export const HttpMethodSchema = Type.Union(
+  [
+    Type.Literal(HttpMethod.GET),
+    Type.Literal(HttpMethod.POST),
+    Type.Literal(HttpMethod.PUT),
+    Type.Literal(HttpMethod.DELETE),
+    Type.Literal(HttpMethod.PATCH),
+    Type.Literal(HttpMethod.HEAD),
+    Type.Literal(HttpMethod.OPTIONS),
+    Type.Literal(HttpMethod.CONNECT),
+    Type.Literal(HttpMethod.TRACE),
+  ],
+  { $id: "HttpMethod" },
+);
+
+export const TargetRefSchema = Type.Object({
+  type: Type.Literal("target"),
+  key: Type.String(),
+});
+export type TargetRef = Static<typeof TargetRefSchema>;
+
+export const EndpointSchema = Type.Object(
+  {
+    id: Type.String(),
+    type: Type.Literal(NodeType.ENDPOINT),
+    method: HttpMethodSchema,
+    path: Type.String(),
+    base: TargetRefSchema,
+    headers: Type.Optional(Type.Record(Type.String(), SecretOrStringSchema)),
+    body: Type.Optional(Type.Any()), // Body can contain nested SecretRefs
+    response_format: ResponseFormatSchema,
+  },
+  { $id: "Endpoint" },
+);
+
+export type Endpoint = Static<typeof EndpointSchema>;
+
+export const FrequencySchema = Type.Object(
+  {
+    every: Type.Number(),
+    unit: Type.Union([
+      Type.Literal(FrequencyUnit.MINUTE),
+      Type.Literal(FrequencyUnit.HOUR),
+      Type.Literal(FrequencyUnit.DAY),
+    ]),
+  },
+  { $id: "Frequency" },
+);
+
+export type Frequency = Static<typeof FrequencySchema>;
+
+export const WaitSchema = Type.Object(
+  {
+    id: Type.String(),
+    type: Type.Literal(NodeType.WAIT),
+    duration_ms: Type.Number(),
+  },
+  { $id: "Wait" },
+);
+export type Wait = Static<typeof WaitSchema>;
+
+export const JSONPathSchema = Type.Array(Type.String());
+export const XMLPathSchema = Type.Array(Type.String());
+export const TextPathSchema = Type.String(); // Is there a regex to validate regex ????
+
+export enum UnaryPredicate {
+  IS_NULL = "IS_NULL",
+  IS_NOT_NULL = "IS_NOT_NULL",
+  IS_TRUE = "IS_TRUE",
+  IS_FALSE = "IS_FALSE",
+  IS_EMPTY = "IS_EMPTY",
+  IS_NOT_EMPTY = "IS_NOT_EMPTY",
+}
+export const UnaryPredicateSchema = Type.Union(
+  [
+    Type.Literal(UnaryPredicate.IS_NULL),
+    Type.Literal(UnaryPredicate.IS_NOT_NULL),
+    Type.Literal(UnaryPredicate.IS_TRUE),
+    Type.Literal(UnaryPredicate.IS_FALSE),
+    Type.Literal(UnaryPredicate.IS_EMPTY),
+    Type.Literal(UnaryPredicate.IS_NOT_EMPTY),
+  ],
+  { $id: "UnaryPredicate" },
+);
+
+export enum BinaryPredicateOperator {
+  EQUAL = "EQUAL",
+  NOT_EQUAL = "NOT_EQUAL",
+  GREATER_THAN = "GREATER_THAN",
+  LESS_THAN = "LESS_THAN",
+  GREATER_THAN_OR_EQUAL = "GREATER_THAN_OR_EQUAL",
+  LESS_THAN_OR_EQUAL = "LESS_THAN_OR_EQUAL",
+  CONTAINS = "CONTAINS",
+  NOT_CONTAINS = "NOT_CONTAINS",
+  STARTS_WITH = "STARTS_WITH",
+  ENDS_WITH = "ENDS_WITH",
+  NOT_STARTS_WITH = "NOT_STARTS_WITH",
+  NOT_ENDS_WITH = "NOT_ENDS_WITH",
+}
+export const BinaryPredicateOperatorSchema = Type.Union(
+  [
+    Type.Literal(BinaryPredicateOperator.EQUAL),
+    Type.Literal(BinaryPredicateOperator.NOT_EQUAL),
+    Type.Literal(BinaryPredicateOperator.GREATER_THAN),
+    Type.Literal(BinaryPredicateOperator.LESS_THAN),
+    Type.Literal(BinaryPredicateOperator.GREATER_THAN_OR_EQUAL),
+    Type.Literal(BinaryPredicateOperator.LESS_THAN_OR_EQUAL),
+    Type.Literal(BinaryPredicateOperator.CONTAINS),
+    Type.Literal(BinaryPredicateOperator.NOT_CONTAINS),
+    Type.Literal(BinaryPredicateOperator.STARTS_WITH),
+    Type.Literal(BinaryPredicateOperator.ENDS_WITH),
+    Type.Literal(BinaryPredicateOperator.NOT_STARTS_WITH),
+    Type.Literal(BinaryPredicateOperator.NOT_ENDS_WITH),
+  ],
+  { $id: "BinaryPredicateOperator" },
+);
+
+export const BinaryPredicateSchema = Type.Object(
+  {
+    expected: Type.Any(),
+    operator: BinaryPredicateOperatorSchema,
+  },
+  { $id: "BinaryPredicate" },
+);
+
+export type BinaryPredicate = Static<typeof BinaryPredicateSchema>;
+export const JSONAssertionSchema = Type.Object(
+  {
+    nodeId: Type.String(),
+    accessor: Type.Union([
+      Type.Literal("body"),
+      Type.Literal("headers"),
+      Type.Literal("status"),
+    ]),
+    path: JSONPathSchema,
+    predicate: Type.Union([UnaryPredicateSchema, BinaryPredicateSchema]),
+  },
+  { $id: "JSONAssertion" },
+);
+export type JSONAssertion = Static<typeof JSONAssertionSchema>;
+
+export const XMLAssertionSchema = Type.Object({
+  path: XMLPathSchema,
+  expected: Type.Any(),
+});
+
+export type XMLAssertion = Static<typeof XMLAssertionSchema>;
+export const TextAssertionSchema = Type.Object({
+  path: TextPathSchema,
+  expected: Type.Any(),
+});
+
+export type TextAssertion = Static<typeof TextAssertionSchema>;
+export const AssertionSchema = Type.Union(
+  [
+    Type.Intersect([
+      Type.Object({
+        assertionType: Type.Literal(ResponseFormat.JSON),
+      }),
+      JSONAssertionSchema,
+    ]),
+    Type.Intersect([
+      Type.Object({
+        assertionType: Type.Literal(ResponseFormat.XML),
+      }),
+      XMLAssertionSchema,
+    ]),
+    Type.Intersect([
+      Type.Object({
+        assertionType: Type.Literal(ResponseFormat.TEXT),
+      }),
+      TextAssertionSchema,
+    ]),
+  ],
+  { $id: "Assertion" },
+);
+export type Assertion = Static<typeof AssertionSchema>;
+
+export const AssertionsSchema = Type.Object(
+  {
+    id: Type.String(),
+    type: Type.Literal(NodeType.ASSERTION),
+    assertions: Type.Array(AssertionSchema),
+  },
+  { $id: "Assertions" },
+);
+export type Assertions = Static<typeof AssertionsSchema>;
+
+export const NodeTypeSchema = Type.Union(
+  [
+    Type.Literal(NodeType.ENDPOINT),
+    Type.Literal(NodeType.WAIT),
+    Type.Literal(NodeType.ASSERTION),
+  ],
+  { $id: "NodeType" },
+);
+
+export const NodeSchema = Type.Union(
+  [EndpointSchema, WaitSchema, AssertionsSchema],
+  { $id: "Node" },
+);
+
+export const EdgeSchema = Type.Object(
+  {
+    from: Type.String(),
+    to: Type.String(),
+  },
+  { $id: "Edge" },
+);
+export type Node = Static<typeof NodeSchema>;
+export type Edge = Static<typeof EdgeSchema>;
+
+export const TestPlanV1Schema = Type.Object(
+  {
+    organization: Type.Optional(Type.String()), // TODO: make these required
+    project: Type.Optional(Type.String()), // TODO: make these required
+    locations: Type.Optional(Type.Array(Type.String())),
+    id: Type.Readonly(Type.String()),
+    name: Type.String(),
+    version: Type.Literal("1.0"),
+    frequency: Type.Optional(FrequencySchema),
+    environment: Type.String({ default: "default" }),
+    nodes: Type.Array(NodeSchema),
+    edges: Type.Array(EdgeSchema),
+  },
+  {
+    $id: "TestPlanV1",
+  },
+);
+export type TestPlanV1 = Static<typeof TestPlanV1Schema>;