home / skills / openai / openai-agents-js / integration-tests

integration-tests skill

safe

/.codex/skills/integration-tests

This skill runs integration tests with a local Verdaccio registry, orchestrating setup, publish, and test steps to validate workflows in your repo.

npx playbooks add skill openai/openai-agents-js --skill integration-tests

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: integration-tests
description: Run the integration-tests pipeline that depends on a local npm registry (Verdaccio). Use when asked to execute integration tests or local publish workflows in this repo.
---

# Integration Tests

## Overview

Run integration tests that require a local npm registry by starting `pnpm local-npm:start` in a background subprocess, executing the build/reset/publish/test pipeline in the main process, then cleanly shutting down the registry process and returning results.

## Workflow

### 1. Start the local registry (subprocess)

- Start a background process with `pnpm local-npm:start` and keep its session id so it can be stopped later.
- Wait until the registry is ready (look for a Verdaccio listen message or the default `http://localhost:4873` line). If no explicit ready line appears, wait a few seconds and proceed.
- If the port is already in use, note that an existing registry may be running and proceed only if it matches the expected local registry; otherwise stop it and restart.

### 2. Run the main pipeline (main process)

Run this exact sequence in the main process and capture the output:

```bash
pnpm i && pnpm build && pnpm local-npm:reset && pnpm local-npm:publish && pnpm test:integration
```

- Return the full success/failure outcome and a concise summary of the results.
- Always capture the stdout/stderr from `pnpm test:integration` and include it in the final response (trim obvious noise if extremely long) inside a fenced code block.
- Do not use watch mode.

#### If `pnpm local-npm:publish` fails

Troubleshoot using `integration-tests/README.md`, which lists the canonical recovery steps. If time is short, prioritize the fixes in the order given there and surface the exact error text in your response.

### 3. Clean up the registry process

- Send Ctrl+C to the registry subprocess and wait for it to exit.
- If it does not exit, terminate it by PID and confirm the port is free before finishing.

## Output expectations

- Always include the integration test results in the response.
- If any step fails, include the failing command, the error output summary, and the next recommended action.

Overview

This skill runs the integration-tests pipeline that depends on a local npm registry (Verdaccio). It manages a background local registry process, runs the exact build/publish/test pipeline, captures test output, and shuts down the registry cleanly. The skill returns a concise result summary plus the full integration test stdout/stderr.

How this skill works

The skill starts a background subprocess for the local registry with pnpm local-npm:start and waits until the registry signals readiness or a short timeout elapses. It then executes: pnpm i && pnpm build && pnpm local-npm:reset && pnpm local-npm:publish && pnpm test:integration in the main process while capturing all output. After the pipeline finishes, the skill sends an interrupt to the registry subprocess and ensures the process and port are cleaned up before returning results.

When to use it

When asked to run integration tests that require a local npm registry.
When validating local publish workflows that simulate npm publishing.
When CI or local debugging requires reproducing the full build/publish/test sequence.
Before merging changes that touch package publishing or cross-package integration.

Best practices

Ensure no other service is occupying the Verdaccio port (default 4873) before starting.
Run from a clean working directory and avoid watch mode during tests.
If publish fails, capture the exact error text and apply canonical recovery steps in order of impact.
Keep the registry startup logs available to diagnose port conflicts or readiness issues.
Trim extremely long test logs to the essential failure lines when sharing results.

Example use cases

Locally validating that packages publish to a local registry and integration tests pass.
Debugging a failing pnpm local-npm:publish step by reproducing the end-to-end pipeline.
Running integration test suites that require packages to be consumed from a running registry.
Automating a pre-merge check that runs build, local publish, and integration tests.

FAQ

What if the Verdaccio port is already in use?

The skill checks the port and will proceed only if the existing service matches the expected local registry; otherwise it stops and restarts the local registry. If a conflict persists, free the port or reconfigure the registry port before retrying.

What if pnpm local-npm:publish fails?

Capture and surface the exact error text. Follow the canonical recovery steps in order of impact (clean local cache, reset local registry state, reattempt publish). If short on time, prioritize fixes that address authentication, package version conflicts, and network issues.