You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Preflight is a Kotlin-based testing framework for Taxi/Orbital projects. It provides a lightweight wrapper around Kotest's DescribeSpec for writing unit and integration tests against Taxi schemas and Orbital services. The project consists of a multi-module Gradle build with a core runtime library and a Gradle plugin.
6
+
7
+
## Architecture
8
+
9
+
### Core Components
10
+
11
+
-**preflight-runtime**: Core testing DSL and execution engine (`preflight-core/preflight-runtime/`)
12
+
-`OrbitalSpec`: Base test class extending Kotest's DescribeSpec with Taxi/Orbital-specific functionality
13
+
-`PreflightExtension`: Kotest extension that handles Taxi compilation and Orbital service initialization
14
+
-`StubHelper`: Utilities for stubbing external data sources in tests
15
+
- Environment variable support and configuration management
16
+
17
+
-**preflight-gradle-plugin**: Gradle plugin for project integration (`preflight-core/preflight-gradle-plugin/`)
18
+
-`PreflightPlugin`: Main plugin class that configures Kotlin JVM, dependencies, and test execution
19
+
- Automatically sets up JVM toolchain (Java 21), source sets, and test runner configuration
20
+
21
+
### Project Structure
22
+
23
+
The repository uses a composite build structure:
24
+
- Root project includes core modules and example projects as composite builds
25
+
- Example projects demonstrate usage patterns and serve as integration tests
26
+
- Documentation site built with Next.js in `docs/` directory
27
+
28
+
## Common Development Commands
29
+
30
+
### Building and Testing
31
+
```bash
32
+
# Build all modules
33
+
./gradlew build
34
+
35
+
# Run all tests (including example projects)
36
+
./gradlew test
37
+
38
+
# Publish to local Maven repository
39
+
./gradlew publishToMavenLocal
40
+
41
+
# Publish all subprojects to local Maven
42
+
./gradlew publishAllMavenLocal
43
+
```
44
+
45
+
### Working with Example Projects
46
+
```bash
47
+
# Test simple project example
48
+
cd example-projects/simple-project && ./gradlew test
49
+
50
+
# Test project with Orbital dependencies
51
+
cd example-projects/project-with-orbital-dependency && ./gradlew test
52
+
53
+
# Test mixed sources project (Avro, OpenAPI, Taxi)
54
+
cd example-projects/mixed-sources && ./gradlew test
55
+
```
56
+
57
+
### Plugin Development
58
+
```bash
59
+
# Build and test the Gradle plugin specifically
60
+
cd preflight-core/preflight-gradle-plugin && ./gradlew test
61
+
62
+
# Generate version constants (automatically done during build)
63
+
./gradlew generateVersionConstants
64
+
```
65
+
66
+
## Key Conventions
67
+
68
+
### Test Structure
69
+
- Tests extend `OrbitalSpec` class which provides Taxi query execution methods
- Support loading from `test-resources/env.conf` files
85
+
- Override via `env()` or `environmentVariables()` methods in specs
86
+
- Use HOCON format for configuration files
87
+
88
+
## Dependencies and Repositories
89
+
90
+
The project uses:
91
+
- Kotlin 1.9.23 with JVM target 21
92
+
- Kotest 5.8.0 for testing framework
93
+
- Custom Orbital/Taxi libraries from `https://repo.orbitalhq.com/release`
94
+
- Gradle Shadow plugin for fat JAR creation
95
+
- Maven publishing with S3-based Orbital repository
96
+
97
+
## Configuration
98
+
99
+
### Orbital Version Configuration
100
+
The plugin supports configurable Orbital versions via the `preflight` extension:
101
+
102
+
```kotlin
103
+
// Default usage (Orbital 0.36.0-M9)
104
+
plugins {
105
+
id("com.orbitalhq.preflight")
106
+
}
107
+
108
+
// Custom Orbital version
109
+
preflight {
110
+
orbitalVersion ="0.37.0"
111
+
}
112
+
```
113
+
114
+
**Implementation details:**
115
+
- Extension class: `PreflightExtension` in `PreflightPlugin.kt`
116
+
- Default version: "0.36.0-M9"
117
+
- Dependencies are added in `afterEvaluate` block to access extension values
118
+
- Orbital dependencies are injected by plugin, Taxi comes transitively
119
+
120
+
## Version Management
121
+
122
+
Project version is managed centrally in `preflight-core/build.gradle.kts` (currently 0.0.4). The Gradle plugin uses code generation to embed version constants at build time via the `generateVersionConstants` task.
0 commit comments