1.4Element 2: Artifact

The artifact is the primary source of truth for test generation. It is the document that defines what the code should do. Without it, the AI generates tests based on common patterns from its training data -- which may have nothing to do with your actual system.

Types of artifacts:

Artifact Type	When to Use	How to Feed It
OpenAPI/Swagger schema	API endpoint testing	Paste the relevant YAML/JSON section
User story + acceptance criteria	Feature testing	Copy verbatim from Jira/Linear
Database schema (DDL)	Data integrity testing	Paste CREATE TABLE statements
Function signature + docstring	Unit testing	Paste the function code
UI mockup description	Frontend testing	Describe layout, or use vision model with screenshot
Error code catalogue	Error handling testing	Paste the error code table
State machine diagram (text)	Workflow testing	Describe states and transitions

Best practice: Paste, do not describe

Pasting the artifact directly into the prompt is far more effective than describing it. Compare:

Describing the artifact (weak):

The checkout endpoint accepts a cart_id field (required, UUID format) and a
payment_method_id field (required, string) and an optional coupon_code field.

Pasting the artifact (strong):

paths:
  /api/v2/checkout:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [cart_id, payment_method_id]
              properties:
                cart_id:
                  type: string
                  format: uuid
                payment_method_id:
                  type: string
                coupon_code:
                  type: string
                  pattern: "^[A-Z0-9]{8}$"
      responses:
        '201':
          description: Order created successfully
        '400':
          description: Validation error
        '401':
          description: Unauthorized
        '402':
          description: Payment failed
        '409':
          description: Stock conflict

The pasted schema gives the AI exact field names, types, constraints, and response codes. The description is ambiguous and incomplete.

Handling $ref references

When pasting OpenAPI schemas, you must resolve $ref references. The AI cannot follow $ref: '#/components/schemas/Address' if you do not include the Address schema.

Incomplete (will cause hallucinations):

shipping_address:
  $ref: '#/components/schemas/Address'

Complete (AI can generate accurate tests):

shipping_address:
  $ref: '#/components/schemas/Address'

# Include the referenced schema:
components:
  schemas:
    Address:
      type: object
      required: [street, city, country, postal_code]
      properties:
        street:
          type: string
          maxLength: 200
        city:
          type: string
          maxLength: 100
        country:
          type: string
          pattern: "^[A-Z]{2}$"
        postal_code:
          type: string
          maxLength: 20

Common Mistake: Pasting an entire 5000-line OpenAPI spec when you only need 50 lines for one endpoint. This floods the context window with irrelevant information and degrades output quality. Extract only the relevant endpoint and its referenced schemas.