jay-dev-server-test

Stars11

Forks4

UpdatedFebruary 19, 2026 at 11:13

Run Jay Stack dev server with test mode for automated testing and CI. Use when running smoke tests, integration tests, or needing reliable server startup/shutdown. Handles health checks, graceful shutdown, and auto-timeout.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

jay-framework

jay-framework/jay

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software Quality Assurance Analysts and TestersComputer and Mathematical Occupations·SOC 15-1253

SKILL.md

readonly

name	jay-dev-server-test
description	Run Jay Stack dev server with test mode for automated testing and CI. Use when running smoke tests, integration tests, or needing reliable server startup/shutdown. Handles health checks, graceful shutdown, and auto-timeout.

Jay Dev Server Test Mode

Run the Jay Stack dev server with test mode for reliable automated testing.

Quick Start

# Start with test mode (enables endpoints)
yarn jay-stack dev --test-mode

# Start with auto-timeout (implies test mode)
yarn jay-stack dev --timeout 60

# Combined
yarn jay-stack dev --test-mode --timeout 120

Test Endpoints

Endpoint	Method	Response
`/_jay/health`	GET	`{"status":"ready","port":3300,"editorPort":3301,"uptime":5.2}`
`/_jay/shutdown`	POST	`{"status":"shutting_down"}`

Waiting for Server Ready

Poll the health endpoint until ready:

async function waitForServer(timeout = 30000): Promise<string> {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    try {
      const res = await fetch('http://localhost:3300/_jay/health');
      if (res.ok) {
        const { port } = await res.json();
        return `http://localhost:${port}`;
      }
    } catch {
      // Not ready yet
    }
    await new Promise((r) => setTimeout(r, 500));
  }
  throw new Error(`Server not ready within ${timeout}ms`);
}

Graceful Shutdown

curl -X POST http://localhost:3300/_jay/shutdown

Or in code:

await fetch(`${serverUrl}/_jay/shutdown`, { method: 'POST' });

Smoke Test Pattern

import { spawn, ChildProcess } from 'child_process';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

describe('Smoke Tests', () => {
  let serverUrl: string;
  let serverProcess: ChildProcess;

  beforeAll(async () => {
    serverProcess = spawn('yarn', ['dev', '--test-mode'], {
      cwd: process.cwd(),
      shell: true,
    });

    serverUrl = await waitForServer(30000);
  }, 35000);

  afterAll(async () => {
    await fetch(`${serverUrl}/_jay/shutdown`, { method: 'POST' });
  });

  it('renders home page', async () => {
    const res = await fetch(`${serverUrl}/`);
    expect(res.status).toBe(200);
    expect(await res.text()).toContain('<!doctype html>');
  });
});

CI Script Pattern

#!/bin/bash
set -e

# Start with safety timeout
yarn dev --timeout 120 &

# Wait for ready
for i in {1..30}; do
    if curl -s http://localhost:3300/_jay/health | grep -q "ready"; then
        break
    fi
    sleep 1
done

# Run tests
curl -sf http://localhost:3300/ > /dev/null

# Clean shutdown
curl -X POST http://localhost:3300/_jay/shutdown

Working Example

See jay/examples/jay-stack/fake-shop/test/smoke.test.ts for a complete implementation.

Key Points

Always use --test-mode for automated tests
Use --timeout as a safety net in CI
Poll /_jay/health instead of fixed delays
Call /_jay/shutdown in afterAll for clean cleanup
The port may vary; parse it from health response or stdout

More from this repository

same repository

jay-agent-kit

jay-framework/jay

Main entry point for AI agents building jay-stack applications. Use when creating pages, working with headless components, or generating jay-html from contracts. Covers the full workflow from reading contracts to producing valid jay-html pages.

2026-07-0111

jay-dom-refs

jay-framework/jay

DOM access in Jay Stack projects — use refs and jay-html ViewState, not document.querySelector or imperative createElement. Use when writing page.ts interactive logic, overlays, drags, focus, measuring elements, or global listeners.

2026-07-0111

jay-html-authoring

jay-framework/jay

Create and edit jay-html template files with data binding, headless components, conditional rendering, loops, and styling. Also covers directory-based routing in jay-stack. Use when creating pages, editing templates, or setting up routes.

2026-07-0111

jay-cli-commands

jay-framework/jay

Use jay-stack CLI commands for setup, discovery and validation. Covers jay-stack setup (plugin config and references), jay-stack params (discover URL param values for SSG), jay-stack action (run plugin actions), and jay-stack validate (check jay-html and contract files). Use when discovering data, validating files, or running plugin actions.

2026-02-2711

jay-contracts-and-plugins

jay-framework/jay

Read plugin.yaml files and materialized contracts from the agent-kit to understand available components, data shapes, and rendering phases. Use when you need to discover what plugins/contracts exist or understand a contract's tags before creating jay-html.

2026-02-2711

name	jay-dev-server-test
description	Run Jay Stack dev server with test mode for automated testing and CI. Use when running smoke tests, integration tests, or needing reliable server startup/shutdown. Handles health checks, graceful shutdown, and auto-timeout.

Jay Dev Server Test Mode

Run the Jay Stack dev server with test mode for reliable automated testing.

Quick Start

# Start with test mode (enables endpoints)
yarn jay-stack dev --test-mode

# Start with auto-timeout (implies test mode)
yarn jay-stack dev --timeout 60

# Combined
yarn jay-stack dev --test-mode --timeout 120

Test Endpoints

Endpoint	Method	Response
`/_jay/health`	GET	`{"status":"ready","port":3300,"editorPort":3301,"uptime":5.2}`
`/_jay/shutdown`	POST	`{"status":"shutting_down"}`

Waiting for Server Ready

Poll the health endpoint until ready:

async function waitForServer(timeout = 30000): Promise<string> {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    try {
      const res = await fetch('http://localhost:3300/_jay/health');
      if (res.ok) {
        const { port } = await res.json();
        return `http://localhost:${port}`;
      }
    } catch {
      // Not ready yet
    }
    await new Promise((r) => setTimeout(r, 500));
  }
  throw new Error(`Server not ready within ${timeout}ms`);
}

Graceful Shutdown

curl -X POST http://localhost:3300/_jay/shutdown

Or in code:

await fetch(`${serverUrl}/_jay/shutdown`, { method: 'POST' });

Smoke Test Pattern

import { spawn, ChildProcess } from 'child_process';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

describe('Smoke Tests', () => {
  let serverUrl: string;
  let serverProcess: ChildProcess;

  beforeAll(async () => {
    serverProcess = spawn('yarn', ['dev', '--test-mode'], {
      cwd: process.cwd(),
      shell: true,
    });

    serverUrl = await waitForServer(30000);
  }, 35000);

  afterAll(async () => {
    await fetch(`${serverUrl}/_jay/shutdown`, { method: 'POST' });
  });

  it('renders home page', async () => {
    const res = await fetch(`${serverUrl}/`);
    expect(res.status).toBe(200);
    expect(await res.text()).toContain('<!doctype html>');
  });
});

CI Script Pattern

#!/bin/bash
set -e

# Start with safety timeout
yarn dev --timeout 120 &

# Wait for ready
for i in {1..30}; do
    if curl -s http://localhost:3300/_jay/health | grep -q "ready"; then
        break
    fi
    sleep 1
done

# Run tests
curl -sf http://localhost:3300/ > /dev/null

# Clean shutdown
curl -X POST http://localhost:3300/_jay/shutdown

Working Example

See jay/examples/jay-stack/fake-shop/test/smoke.test.ts for a complete implementation.

Key Points

Always use --test-mode for automated tests
Use --timeout as a safety net in CI
Poll /_jay/health instead of fixed delays
Call /_jay/shutdown in afterAll for clean cleanup
The port may vary; parse it from health response or stdout