---
name: ispc-lit-tests
description: Best practices for creating ISPC lit tests. Use when writing regression tests, verifying code generation, or checking compiler diagnostics.
---

# ISPC Lit Tests

A concise guide for writing **lit tests** for the ISPC.
These tests ensure compiler correctness, verify generated code, and prevent regressions.

---

## When to Use Lit Tests

Use lit tests when validating:

- **Compiler output** — LLVM IR, assembly, or AST.
- **Diagnostics** — warnings, errors, or other emitted messages.
- **Platform behavior** — verifying cross-platform or target-specific differences.
- **Regression coverage** — reproducing and locking fixes for known compiler issues.

---

## Core Guidelines

### Always Use `--nowrap`
Prevents line wrapping in compiler output for consistent FileCheck matching:
```ispc
// RUN: %{ispc} %s --target=host --nowrap --emit-llvm-text -o - | FileCheck %s
```

### Use `--nostdlib` When Not Testing Library Code
Simplifies test output and avoids unrelated symbols:
```ispc
// RUN: %{ispc} %s --target=host --nostdlib --nowrap -o - | FileCheck %s
```

## Avoid `export` Unless Testing It

`export` functions generate both masked and unmasked IR — doubling the verification effort.

```ispc
// Preferred
void foo() { ... }

// Avoid unless explicitly testing export behavior
export void foo() { ... }
```

## Target Specification

### Generic / Portable Tests

Use `--target=host` unless verifying target-specific codegen:

```ispc
// RUN: %{ispc} %s --target=host --nowrap -o - | FileCheck %s
```

#### Writing Portable Checks

Avoid hardcoding vector widths or variable names.  
Use named patterns like `[[WIDTH]]` and `[[TYPE]]`.

Example:
```ispc
// CHECK-NEXT:  %test = sdiv <[[WIDTH:.*]] x i32> %a, %b
// CHECK-NEXT:  ret <[[WIDTH]] x i32> %test
```

When order is flexible:
```ispc
// CHECK-DAG: {{%.*}} = shufflevector <[[WIDTH:.*]] x [[BASE_TYPE:i.*]]> {{%.*}}, <[[WIDTH]] x [[BASE_TYPE]]> {{poison|undef}}, <[[WIDTH]] x [[BASE_TYPE]]> zeroinitializer
```

**Tip:** Avoid relying on exact variable names — they differ between OS and LLVM versions.


### Target-Specific Tests

When output differs by architecture or ISA:

- Specify the **exact target and feature**.
- Include a `REQUIRES:` directive for conditional execution.

Example:
```ispc
// RUN: %{ispc} %s --target=avx512skx-x16 --emit-asm -o - | FileCheck %s
// REQUIRES: X86_ENABLED
```

## Using `REQUIRES` for Feature Dependencies

Defined in `tests/lit-tests/lit.cfg`:

- **Features:** `X86_ENABLED`, `LLVM_*_0+`, etc.
- **Substitutions:** `%{ispc}`, `%s`, `%t`
- **Test configuration:** format, suffixes, and substitutions

## Testing Intermediate IR

Use `--debug-phase` to capture output of specific optimization passes:

```ispc
// RUN: %{ispc} %s --target=avx2 --emit-llvm-text \
// RUN:   --debug-phase=325:325 --dump-file=%t -o /dev/null
// RUN: FileCheck --input-file %t/ir_325_LoadStoreVectorizerPass.ll %s
```

## Comments and Documentation

Clearly describe what the test verifies and why it exists.

Example:
```ispc
// Verifies that stmxcsr/ldmxcsr intrinsics correctly set/restore FTZ/DAZ flags
// when --opt=reset-ftz-daz is enabled.
```

## Example Template

```ispc
// Brief description of the test purpose
// RUN: %{ispc} %s --target=host --nostdlib --nowrap --emit-llvm-text -o - | FileCheck %s

// REQUIRES: <feature_if_needed>

// CHECK-LABEL: @function_name___
// CHECK: expected pattern
// CHECK-NOT: unexpected pattern

void function_name() {
    // Minimal reproducible test code here
}
```

## Test commands
Run all lit tests:
```bash
cmake --build build --target check-all -j $(nproc)
```

To test the specific test, run:
```bash
TEST=/full/path/test.ispc cmake --build build --target check-one -j $(nproc)
```

## Test names
- Regression tests: name them `####.ispc`, where #### is the GitHub issue number.
- Other tests: use a short, descriptive name. For multiple tests of one feature, add numbers (e.g., `feature-name-1.ispc`, `feature-name-2.ispc`).

## Key Takeaways

- Keep tests **minimal** — validate one behavior per test.
- Use **portable patterns** for LLVM IR.
- Add **REQUIRES** for target-dependent tests.
- Prefer **non-exported** functions unless necessary.
- Document **intent** and **expected outcome** in comments.