166 lines
4.8 KiB
Markdown
166 lines
4.8 KiB
Markdown
# test-cli.sh usage
|
|
|
|
`test-cli.sh` is the CLI automation test script for qiming-file-server. It verifies locally that `qiming-file-server` can start, report status, answer health checks, restart, and stop.
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Grant execute permission (first time only)
|
|
chmod +x scripts/test-cli.sh
|
|
|
|
# Default: pnpm install + pnpm link, then test
|
|
./scripts/test-cli.sh
|
|
|
|
# Run dist directly (no global link)
|
|
./scripts/test-cli.sh --direct
|
|
|
|
# Already installed globally; skip install steps
|
|
./scripts/test-cli.sh --installed
|
|
```
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
| Dependency | Notes |
|
|
|------------|--------|
|
|
| bash | Script runtime |
|
|
| curl | Health endpoint requests |
|
|
| jq | JSON parsing |
|
|
| pnpm | Required for modes 1 and 2 (optional for mode 3) |
|
|
| node | v22+ recommended |
|
|
|
|
Install example (macOS):
|
|
|
|
```bash
|
|
brew install curl jq
|
|
# Install pnpm / node per project requirements
|
|
```
|
|
|
|
---
|
|
|
|
## Three test modes
|
|
|
|
### Mode 1: Default (pnpm link)
|
|
|
|
- **Command**: `./scripts/test-cli.sh` (no extra flags)
|
|
- **Behavior**:
|
|
- Runs `pnpm install` in the project root
|
|
- Runs `pnpm run build` to compile into `dist/`
|
|
- Runs `pnpm link --global` so `qiming-file-server` is available globally
|
|
- Tests using the global `qiming-file-server` command
|
|
- **Use when**: Local development, first-time verification, or when not installed globally
|
|
|
|
### Mode 2: Direct run (`--direct`)
|
|
|
|
- **Command**: `./scripts/test-cli.sh --direct`
|
|
- **Behavior**:
|
|
- Does not run `pnpm link`; runs `node dist/cli.js` directly
|
|
- Requires a built project: `dist/` exists and `dist/cli.js` exists
|
|
- **Prerequisite**: Run `pnpm run build` first
|
|
- **Use when**: You do not want to change global commands and only want to test the current build
|
|
|
|
### Mode 3: Installed (`--installed`)
|
|
|
|
- **Command**: `./scripts/test-cli.sh --installed`
|
|
- **Behavior**:
|
|
- No install, no build, no link; calls the installed `qiming-file-server` directly
|
|
- Fails with a hint if `qiming-file-server` is not found
|
|
- **Prerequisite**: Installed via `npm install -g qiming-file-server` or `pnpm link --global`
|
|
- **Use when**: Verifying a global install, CI, or an environment where the CLI is already installed
|
|
|
|
---
|
|
|
|
## Command-line options
|
|
|
|
| Option | Short | Description | Default |
|
|
|--------|-------|-------------|---------|
|
|
| `--port <port>` | `-p` | Port for the test server | `60000` |
|
|
| `--direct` | — | Mode 2: run dist with Node directly | — |
|
|
| `--installed` | — | Mode 3: use globally installed CLI | — |
|
|
| `--project-dir <dir>` | — | Project directory | `./test-projects` |
|
|
| `--nginx-dir <dir>` | — | Nginx directory | `./test-nginx` |
|
|
| `--upload-dir <dir>` | — | Upload directory | `./test-uploads` |
|
|
| `--help` | `-h` | Show help | — |
|
|
|
|
---
|
|
|
|
## Environment variables
|
|
|
|
These override defaults (equivalent to CLI options where applicable):
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `PORT` | Server port | `60000` |
|
|
| `PROJECT_DIR` | Project directory | `./test-projects` |
|
|
| `NGINX_DIR` | Nginx directory | `./test-nginx` |
|
|
| `UPLOAD_DIR` | Upload directory | `./test-uploads` |
|
|
|
|
Example:
|
|
|
|
```bash
|
|
PORT=60001 ./scripts/test-cli.sh --installed
|
|
```
|
|
|
|
---
|
|
|
|
## Test flow
|
|
|
|
The script runs in order:
|
|
|
|
1. **Test 1: Start** — `start --env production --port <PORT>`, wait ~3 seconds.
|
|
2. **Test 2: Health** — `GET http://localhost:<PORT>/health`, assert `status === "ok"` in JSON.
|
|
3. **Test 3: Status** — `status`, check output looks normal.
|
|
4. **Test 4: Restart** — `restart`, wait ~3 seconds.
|
|
5. **Test 5: Health after restart** — `GET /health` again.
|
|
6. **Test 6: Stop** — `stop`.
|
|
|
|
On exit or error, cleanup runs (stop service; mode 1 also runs `pnpm unlink --global`).
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Default mode, default port 60000
|
|
./scripts/test-cli.sh
|
|
|
|
# Mode 2, custom port 60001
|
|
./scripts/test-cli.sh --direct --port 60001
|
|
|
|
# Mode 3, custom port
|
|
./scripts/test-cli.sh --installed -p 60001
|
|
|
|
# Custom project/nginx/upload dirs
|
|
./scripts/test-cli.sh --project-dir ./my-projects --nginx-dir ./my-nginx --upload-dir ./my-uploads
|
|
|
|
# Help
|
|
./scripts/test-cli.sh --help
|
|
```
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
**Q: `dist` missing or `dist/cli.js` missing?**
|
|
A: Run `pnpm run build` before `--direct`, or use the default mode (builds automatically).
|
|
|
|
**Q: `qiming-file-server` command not found?**
|
|
A: For `--installed`, install globally first, e.g. `npm install -g qiming-file-server` or `pnpm link --global` in this repo. Or use default mode or `--direct`.
|
|
|
|
**Q: Port in use?**
|
|
A: Use `-p`/`--port` or `PORT`, e.g. `./scripts/test-cli.sh -p 60001`.
|
|
|
|
**Q: Missing curl / jq?**
|
|
A: The script checks dependencies and reports. On macOS: `brew install curl jq`.
|
|
|
|
---
|
|
|
|
## Related docs
|
|
|
|
- [QUICK_START.md](./QUICK_START.md) — Quick start
|
|
- [ENV.md](./ENV.md) — Environment and configuration
|
|
- [CLAUDE.md](../CLAUDE.md) / [AGENTS.md](../AGENTS.md) — Project layout and conventions
|