AGENTS.md

1# FIR Analysis Tests
2 
3Location: `compiler/testData/diagnostics`
4 
5## Test File Format (`.kt` files)
6 
7### Header Directives
8 
9Comment lines at the top of the file control test behavior:
10 
11| Directive                                                 | Description                                                                                                                                                      |
12|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
13| `// RUN_PIPELINE_TILL: FRONTEND`, `BACKEND` or `FIR2IR`   | How far the compiler pipeline runs (FRONTEND = FIR resolution only, BACKEND = through codegen, FIR2IR = rarely once IR has been created, but failing at backend) |
14| `// ISSUE: KT-XXXXX`                                      | References a YouTrack issue                                                                                                                                      |
15| `// WITH_STDLIB`                                          | Include stdlib in test classpath                                                                                                                                 |
16| `// LANGUAGE: +FeatureName` / `// LANGUAGE: -FeatureName` | Enable/disable language features                                                                                                                                 |
17| `// DIAGNOSTICS: -DIAGNOSTIC_NAME`                        | Suppress specific diagnostics                                                                                                                                    |
18| `// RENDER_DIAGNOSTICS_FULL_TEXT`                         | Produces `.fir.diag.txt` with human-readable error messages                                                                                                      |
19| `// RENDER_DIAGNOSTIC_ARGUMENTS`                          | Renders arguments inside markers, e.g. `<!TYPE_MISMATCH("A; B")!>`                                                                                               |
20| `// DUMP_CFG` / `// DUMP_CFG: FLOW`                       | Generates `.dot` file with control flow graph                                                                                                                    |
21| `// DUMP_INFERENCE_LOGS: option1, option2`                | Possible options: FIXATION, MARKDOWN, MERMAID                                                                                                                    |
22| `// CHECK_TYPE`                                           | Enables `checkType { _<Type>() }` pattern for type assertions                                                                                                    |
23| `// FILE: Name.kt` / `// FILE: Name.java`                 | Multi-file test (splits single `.kt` file into virtual files)                                                                                                    |
24| `// LATEST_LV_DIFFERENCE`                                 | Indicates test expectations differ between stable and latest language version (see `.latestLV.kt` below)                                                         |
25 
26### Inline Diagnostic Markers
27 
28Diagnostic assertions are placed inline around the code that should produce them:
29 
30- `<!DIAGNOSTIC_NAME!>code<!>` — asserts `code` produces that diagnostic
31- `<!DIAGNOSTIC_NAME("arg1; arg2")!>code<!>` — with diagnostic arguments (needs `RENDER_DIAGNOSTIC_ARGUMENTS`)
32- `<!DIAG1, DIAG2!>code<!>` — multiple diagnostics on same code span
33 
34### Debug Info Markers
35 
36- `<!DEBUG_INFO_CALL("fqName: ...; typeCall: ...")!>call<!>` — asserts call resolution target
37- `<!DEBUG_INFO_EXPRESSION_TYPE("type")!>expr<!>` — asserts expression type
38 
39### Footer
40 
41- `/* GENERATED_FIR_TAGS: tag1, tag2, ... */` — auto-generated tags listing FIR constructs present in the file; do not hand-edit
42 
43## Associated Files (auto-generated, not hand-edited)
44 
45| Extension        | Content                                                             | Generated when                                    |
46|------------------|---------------------------------------------------------------------|---------------------------------------------------|
47| `.fir.txt`       | FIR tree dump (resolved FIR with `R\|...\|` references)             | Only when `FIR_DUMP` directive is present         |
48| `.fir.diag.txt`  | Diagnostics in text format (`/file.kt:(offset): severity: message`) | `RENDER_DIAGNOSTICS_FULL_TEXT` directive present  |
49| `.dot`           | Control flow graph in Graphviz format                               | `DUMP_CFG` directive present                      |
50| `.fixation.txt`  | Type variable fixation process                                      | `DUMP_INFERENCE_LOGS: FIXATION` directive present |
51| `.inference.md`  | General type inference logs                                         | `DUMP_INFERENCE_LOGS: MARKDOWN` directive present |
52| `.inference.mmd` | General type inference logs via Mermaid format                      | `DUMP_INFERENCE_LOGS: MERMAID` directive present  |
53| `.latestLV.kt`   | Test expectations for latest language version when they differ from stable | `LATEST_LV_DIFFERENCE` directive present     |
54 
55## Latest Language Version Differences
56 
57When a language feature has `sinceVersion` set to a future Kotlin version (e.g., `KOTLIN_2_5`), it is disabled at the stable language version but enabled at the latest language version. This causes different compiler behavior depending on which LV the test runs with.
58 
59To handle this:
601. Add `// LATEST_LV_DIFFERENCE` directive to the `.kt` test file
612. Create a `.latestLV.kt` file (for diagnostics tests: `.fir.latestLV.kt` if only FIR behavior differs) containing the full test with diagnostic expectations for the latest LV
623. The base `.kt` file keeps expectations for the stable (default) language version
63 
64The latest-LV test runners (`FirLightTreeDiagnosticsWithLatestLanguageVersionTestGenerated`, `FirLightTreeOldFrontendDiagnosticsWithLatestLanguageVersionTestGenerated`) use the `.latestLV.kt` file instead of the base `.kt` file.
65 
66Run with `-Pkotlin.test.update.test.data=true` to auto-generate/update `.latestLV.kt` content.
67 
68## Creating a New Test
69 
701. **Create the `.kt` test file** with appropriate directives and test code.
712. **Regenerate test runners**: `./gradlew generateTests` — updates `*Generated.java` files to include the new test method.
723. **Run the test once** (it will fail):
73```bash
74   ./gradlew :compiler:fir:analysis-tests:test --tests &quot;org.jetbrains.kotlin.test.runners.PhasedJvmDiagnosticLightTreeTestGenerated\$Resolve\$Problems.testMyTest&quot;
75```
76   This first run auto-generates the `GENERATED_FIR_TAGS` footer in the `.kt` file. No special flags are needed — tags are written automatically on first run.
774. **Run the test again** — it should now pass.
78 
79### Important notes
80 
81- **`RUN_PIPELINE_TILL` must match actual test needs.** If the test has no expected diagnostics/errors, the framework requires `BACKEND`. Using `FRONTEND` when `BACKEND` is possible causes a "Phase FRONTEND could be promoted to BACKEND" failure.
82- **`GENERATED_FIR_TAGS` are written automatically** on the first test run when absent. Do not add them manually. Just run the test, let it fail and write the tags, then run again.
83- **`.fir.txt` is NOT generated by default.** It requires a `// FIR_DUMP` directive. Most tests (especially simple regression tests) do not need it.
84- **stdlib is not available by default.** Functions like `println` will produce `UNRESOLVED_REFERENCE` without the `// WITH_STDLIB` directive.
85- **`-Pkotlin.test.update.test.data=true`** updates handler-generated files (like `.fir.txt`) but does NOT update the `.kt` source file itself (tags, diagnostic markers). The `.kt` file is updated by the test framework's own `TagsGeneratorChecker` on a normal test run.
86 
87## Directory Structure at `testData/resolve/`
88 
89Root level contains individual `.kt` test files with their `.fir.txt` dumps. Subdirectories group tests by topic:
90 
91- `annotations/`, `arguments/`, `arrays/` — basic language constructs
92- `builtins/`, `stdlib/` — standard library interactions
93- `callResolution/` — call resolution scenarios (overloads, invoke, SAM, operators)
94- `cfa/`, `cfg/` — control flow analysis and graphs
95- `checkers/`, `extraCheckers/`, `diagnostics/` — diagnostic-focused tests
96- `collectionLiterals/`, `constructors/`, `constVal/` — specific constructs
97- `contextParameters/`, `contextSensitiveResolutionUsingExpectedType/` — context-dependent resolution
98- `contracts/` — Kotlin contracts
99- `delegates/`, `destructuring/` — delegation and destructuring
100- `exhaustiveness/` — exhaustive when/sealed checks
101- `expresssions/` (note: misspelled in repo), `fromBuilder/` — expression-level tests
102- `headerMode/` — header/expect declarations
103- `inference/` — type inference
104- `inlineClasses/`, `innerClasses/`, `localClasses/` — class variants
105- `j+k/` — Java-Kotlin interop
106- `multifile/` — multi-file tests (using `// FILE:` directive)
107- `multiplatform/` — multiplatform expect/actual
108- `nestedTypeAliases/`, `typeArguments/`, `typeParameters/`, `types/` — type system
109- `overloadResolution/`, `overrides/` — overloading and overriding
110- `problems/` — regression/bug scenarios
111- `properties/`, `propertyVsField/` — property resolution
112- `qualifiers/`, `references/` — qualified access and references
113- `returnInExpressionBodies/` — return in expression body functions
114- `samConstructors/`, `samConversions/` — SAM conversion tests
115- `scopes/`, `visibility/` — scoping and visibility
116- `scripts/` — Kotlin scripting
117- `smartcasts/` — smart cast tests
118- `suppress/` — @Suppress annotation tests
119- `unqualifiedEnum/` — unqualified enum access
120- `vfir/` — virtual FIR tests
121- `withAllowedKotlinPackage/` — tests allowing kotlin package
122