# How to Write a `test-prompts.json` File in Darwin-Compatible Format for Cangjie Skill

> Learn to write test-prompts.json in Darwin-compatible format for Cangjie skill. Ensure reliable macOS parsing with UTF-8 encoding, LF line endings, and no trailing commas.

- Repository: [kangarooking/cangjie-skill](https://github.com/kangarooking/cangjie-skill)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Save [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) as UTF‑8 without BOM, use LF line endings only, avoid trailing commas, and place it in the repository root to ensure reliable parsing on macOS.**

The [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) file drives automated prompt testing in the Cangjie skill repository (`kangarooking/cangjie-skill`). When you create or edit this file on macOS, following Darwin-specific formatting conventions prevents subtle parsing failures that can break the test runner.

## Key File Encoding Requirements for macOS

### UTF-8 Without Byte Order Mark

The test runner reads [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) as plain UTF‑8. While macOS defaults to UTF‑8, some editors silently save files with a **byte order mark (BOM)** or as **UTF‑16**, which corrupts JSON parsing.

- **Check in VS Code**: Status bar shows "UTF‑8" — click to change if needed.
- **Check in terminal**: `file test-prompts.json` should return `test-prompts.json: JSON text data`.

### LF Line Endings Only

Line endings matter because the diff‑based test harness may treat carriage returns (`\r`) as literal characters inside prompt strings.

| Line Ending | Risk on macOS |
|-------------|---------------|
| CRLF (`\r\n`) | Trailing `\r` appears in string comparisons |
| LF (`\n`) | **Correct** — standard Unix/macOS format |

Set your editor to **Unix/LF** mode before editing. In VS Code, click the line ending indicator in the status bar and select "LF".

## JSON Syntax Rules for Cross-Platform Compatibility

### No Trailing Commas

JSON strictly forbids trailing commas after the last element. Some editors and formatters insert these automatically — disable that behavior for this file.

**Incorrect:**

```json
{
  "id": "example",
  "prompt": "test",
}

```

**Correct:**

```json
{
  "id": "example",
  "prompt": "test"
}

```

### Forward Slashes for Paths

If your prompt definitions embed file paths, always use forward slashes (`/`). Backslashes serve as escape characters in JSON strings, causing malformed paths.

**Correct path format:**

```json
"fixturePath": "fixtures/characters.json"

```

## File Location and Permissions

The skill runner expects [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) at the **repository root** — the same directory as [`README.md`](https://github.com/kangarooking/cangjie-skill/blob/main/README.md). Placing it elsewhere causes silent test failures.

```bash

# Verify location

ls -la test-prompts.json

# Should show: -rw-r--r-- (readable by all, writable by owner)

```

No executable permission is required. The template at `templates/test-prompts.json.template` provides the starting structure.

## Step-by-Step Creation Workflow

1. **Copy the template**

   ```bash
   cp templates/test-prompts.json.template test-prompts.json
   ```

2. **Verify editor settings** — UTF‑8 encoding, LF line endings, plain text mode.

3. **Edit prompt definitions** using the structure shown below.

4. **Validate syntax**

   ```bash
   python -m json.tool test-prompts.json > /dev/null && echo "Valid JSON"
   ```

5. **Commit** — the file is now compatible with macOS and Linux test runners.

## Darwin-Compatible [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) Example

```json
[
  {
    "id": "basic-cangjie-lookup",
    "prompt": "What is the Cangjie code for the character \"愛\"?",
    "expected": "愛 → 愛",
    "description": "Simple lookup of a common Chinese character."
  },
  {
    "id": "invalid-character",
    "prompt": "Give the Cangjie code for the emoji \"😀\".",
    "expectedError": "Unsupported character",
    "description": "Ensures the skill gracefully rejects non-Chinese input."
  }
]

```

This file uses:
- Pure UTF‑8 encoding (no BOM)
- LF line endings
- Standard JSON without trailing commas
- Forward slashes in any path references

## Running Tests on macOS

With a properly formatted file, the test runner executes without platform-specific adjustments:

```bash
python -m cangjie_skill.tests.run

```

The runner automatically loads [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) from the repository root according to the implementation in `kangarooking/cangjie-skill`.

## Summary

- **Save as UTF‑8 without BOM** — prevents encoding-related parse errors.
- **Use LF line endings** — avoids spurious character mismatches in string comparisons.
- **Omit trailing commas** — required for strict JSON compliance.
- **Write paths with forward slashes** — backslashes act as escape characters.
- **Place in repository root** — the skill runner does not search subdirectories.
- **Validate with `python -m json.tool`** — catches syntax errors before running tests.

## Frequently Asked Questions

### Why does my [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) fail on macOS but work on Linux?

Most likely your file has **CRLF line endings** or a **UTF‑8 BOM**. Run `file test-prompts.json` to check encoding, and `od -c test-prompts.json | head` to inspect line endings. Re-save with LF-only and no BOM.

### Can I use comments in [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json)?

No — standard JSON does not support comments. Add descriptive text to the `description` field of each prompt object instead, as shown in the example above.

### What happens if I put [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) in a subdirectory?

The test runner will not find it. According to the source structure, the file must reside at the repository root. The template at `templates/test-prompts.json.template` exists only as a copy source, not as a working location.

### Is the template file already Darwin-compatible?

Yes — `templates/test-prompts.json.template` uses UTF‑8 and LF line endings. However, your editor may change these settings when you copy and edit the file, so always verify encoding and line endings before saving.