Skip to content

Commit c1635c6

Browse files
martypittmartypitt
committed
docs updates
1 parent 59c83e4 commit c1635c6

File tree

6 files changed

+627
-4
lines changed

6 files changed

+627
-4
lines changed

‎RELEASE_ANNOUNCEMENT_0.0.4.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# 🚀 Preflight 0.0.4 Released: MongoDB Support, Direct Orbital API Access, and More!
2+
3+
We're excited to announce the release of **Preflight 0.0.4**, the biggest update yet to our Kotlin testing framework for Taxi and Orbital projects! This release brings significant new capabilities for integration testing, enhanced API access, and improved developer experience.
4+
5+
## 🎯 What's New
6+
7+
### 🗄️ MongoDB Container Support
8+
The most requested feature is finally here! Preflight now provides first-class support for testing against MongoDB databases using TestContainers.
9+
10+
```kotlin
11+
// Configure MongoDB connector
12+
preflight {
13+
connectors = listOf(
14+
ConnectorSupport.Kafka,
15+
ConnectorSupport.MongoDB // New!
16+
)
17+
}
18+
19+
// Use in your tests
20+
class MongoIntegrationSpec : OrbitalSpec({
21+
withContainers(
22+
mongoConnector("user-db")
23+
)
24+
25+
it("should query users from MongoDB") {
26+
val mongo = containerForConnection<MongoContainerSupport>("user-db")
27+
28+
// Insert test data
29+
mongo.mongoClient()
30+
.getDatabase("user_management")
31+
.getCollection("users")
32+
.insertOne(Document("id", "user123").append("name", "John"))
33+
34+
// Test your Taxi queries
35+
"""find { User(UserId == "user123") }""".queryForObject()
36+
.shouldBe(mapOf("id" to "user123", "name" to "John"))
37+
}
38+
})
39+
```
40+
41+
**Key Features:**
42+
- Pre-configured MongoDB 6.0.7 containers
43+
- Automatic database initialization with test credentials
44+
- Direct MongoDB client access for test data setup
45+
- Seamless integration with existing Kafka containers
46+
47+
### 🔧 Direct Orbital API Access
48+
Need more control? Access the underlying Orbital instance directly for advanced testing scenarios:
49+
50+
```kotlin
51+
it("should access Orbital API for advanced testing") {
52+
val orbital = orbital()
53+
54+
// Inspect compiled schema
55+
val schema = orbital.schema
56+
val userType = schema.type("User")
57+
58+
// Execute queries with custom parameters
59+
val result = orbital.query("""
60+
given { userId : UserId = parameter("userId") }
61+
find { User(id == userId) }
62+
""", QueryContext.builder().withParameter("userId", "123").build())
63+
64+
// Access internal services
65+
val invoker = orbital.operationInvoker
66+
}
67+
```
68+
69+
**Use Cases:**
70+
- Schema metadata inspection and validation
71+
- Custom query execution with parameters
72+
- Advanced debugging and introspection
73+
- Testing Orbital's internal behavior
74+
75+
### 📊 Mixed Source Format Support
76+
Preflight now automatically handles projects with multiple schema formats:
77+
78+
```kotlin
79+
// Your project structure
80+
├── src
81+
│ ├── taxi-schemas/
82+
│ │ └── user.taxi
83+
│ ├── avro-schemas/ // New!
84+
│ │ └── events.avsc
85+
│ └── openapi-specs/ // New!
86+
│ └── api.yaml
87+
```
88+
89+
**Automatic Transpilation:**
90+
- **Avro schemas** (`.avsc`) → Taxi types
91+
- **OpenAPI specs** (`.yaml`, `.json`) → Taxi services
92+
- **Taxi schemas** (`.taxi`) → Native support
93+
- All formats unified in a single compiled schema for testing
94+
95+
### ⚙️ Enhanced Configuration
96+
More control over your testing environment:
97+
98+
```kotlin
99+
preflight {
100+
// Customize Orbital version
101+
orbitalVersion = "0.37.0" // or "0.37.0-M1" for milestones
102+
103+
// Use multiple connectors
104+
connectors = listOf(
105+
ConnectorSupport.Kafka,
106+
ConnectorSupport.MongoDB
107+
)
108+
}
109+
```
110+
111+
### 🎯 Named Query Arguments
112+
Pass arguments to your named queries in tests:
113+
114+
```kotlin
115+
it("should execute named queries with arguments") {
116+
runNamedQueryForObject("getUserWithDetails", mapOf(
117+
"userId" to "user123",
118+
"includePreferences" to true
119+
)) {
120+
// Configure stubs as needed
121+
}
122+
}
123+
```
124+
125+
## 🔄 Breaking Changes
126+
127+
### Java 21 Requirement
128+
**Action Required:** Preflight 0.0.4 requires Java 21 (previously Java 17).
129+
130+
```bash
131+
# Update your JAVA_HOME
132+
export JAVA_HOME=/path/to/java-21
133+
134+
# Verify version
135+
java -version
136+
# Should show: java version "21.x.x"
137+
```
138+
139+
Update your Gradle builds to use Java 21:
140+
```kotlin
141+
kotlin {
142+
jvmToolchain(21)
143+
}
144+
```
145+
146+
## 📚 Improved Documentation
147+
148+
We've significantly expanded our documentation with:
149+
- Complete MongoDB integration testing guide
150+
- Direct Orbital API access examples
151+
- Mixed source format documentation
152+
- Enhanced getting started guide
153+
- Comprehensive changelog (new!)
154+
155+
## 🚀 Getting Started
156+
157+
### New Projects
158+
```kotlin
159+
// build.gradle.kts
160+
plugins {
161+
kotlin("jvm") version "1.9.23"
162+
id("com.orbitalhq.preflight") version "0.0.4"
163+
}
164+
165+
preflight {
166+
orbitalVersion = "0.36.0-M9" // or your preferred version
167+
connectors = listOf(
168+
ConnectorSupport.Kafka,
169+
ConnectorSupport.MongoDB
170+
)
171+
}
172+
```
173+
174+
### Existing Projects
175+
Update your plugin version:
176+
```kotlin
177+
id("com.orbitalhq.preflight") version "0.0.4" // was "0.0.3"
178+
```
179+
180+
## 🎉 What's Next?
181+
182+
Looking ahead to future releases, we're exploring:
183+
- PostgreSQL container support
184+
- REST API mocking with WireMock
185+
- Enhanced streaming test utilities
186+
- Performance improvements and optimizations
187+
- Integration with Nebula for real data source testing
188+
189+
## 📖 Resources
190+
191+
- **Documentation:** [Latest docs with all new features](https://preflight.orbitalhq.com)
192+
- **Changelog:** [Complete version history](https://preflight.orbitalhq.com/changelog)
193+
- **Examples:** Check out our [example projects](https://github.com/orbitalapi/preflight/tree/main/example-projects)
194+
- **Issues:** [Report bugs or request features](https://github.com/orbitalapi/preflight/issues)
195+
196+
## 🙏 Thank You
197+
198+
A huge thanks to our community for the feedback, bug reports, and feature requests that made this release possible. Special shoutout to everyone who contributed to testing the MongoDB integration!
199+
200+
---
201+
202+
**Happy Testing!** 🧪
203+
204+
*The Orbital Team*
205+
206+
---
207+
208+
### Version Compatibility
209+
- **Preflight:** 0.0.4
210+
- **Orbital:** 0.36.0-M9 (default, configurable)
211+
- **Java:** 21+ (required)
212+
- **Kotlin:** 1.9.23
213+
- **Gradle:** 7.0+ (recommended: 8.0+)

‎docs/pages/_meta.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@ export default {
55
"stubbing" : "Stubbing responses",
66
"integration-testing": "Integration testing",
77
"environment-variables" : "Environment variables",
8+
"changelog": "Changelog",
89
"faq" : "Tips and FAQ's"
910
};

‎docs/pages/changelog.mdx‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
title: Changelog
3+
---
4+
5+
# Changelog
6+
7+
All notable changes to Preflight will be documented in this file.
8+
9+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
10+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
11+
12+
## [0.0.4] - 2025-08-14
13+
14+
### ✨ Added
15+
- **MongoDB Container Support**: Full integration testing support for MongoDB databases
16+
- New `ConnectorSupport.MongoDB` connector type
17+
- `mongoConnector()` helper for easy container setup
18+
- `MongoContainerSupport` API with direct MongoDB client access
19+
- Automatic database initialization with test credentials
20+
- **Multiple Connector Support**: Use multiple container types in the same test spec
21+
- Configure both Kafka and MongoDB connectors simultaneously
22+
- Isolated container instances per connection name
23+
- **Direct Orbital API Access**: Access underlying Orbital instance via `orbital()` method
24+
- Full access to compiled schema metadata
25+
- Custom query execution with parameters and context
26+
- Advanced operation testing and debugging capabilities
27+
- **Named Query Arguments**: Pass arguments to named queries in tests
28+
- Enhanced `runNamedQueryForObject()` method with argument support
29+
- Better integration with parameterized Taxi queries
30+
- **Mixed Source Transpilation**: Automatic support for multiple schema formats
31+
- Transparent handling of Avro (`.avsc`) files
32+
- OpenAPI specification (`.yaml`, `.json`) support
33+
- Unified compilation process for mixed-format projects
34+
35+
### 🔧 Enhanced
36+
- **Configurable Orbital Version**: Customize which Orbital version to test against
37+
- Set `orbitalVersion` in preflight extension
38+
- Support for both release and milestone versions (e.g., "0.37.0-M1")
39+
- Improved dependency management and version compatibility
40+
- **Integration Testing Documentation**: Comprehensive guides and examples
41+
- Complete MongoDB container usage examples
42+
- Multi-connector configuration patterns
43+
- Advanced container interaction APIs
44+
45+
### 🏗️ Infrastructure
46+
- **JVM 21 Support**: Updated to Java 21 as the target JVM version
47+
- **Enhanced Build System**: Improved dependency loading and transpilation
48+
- **Environment Variable Support**: Better handling of test configuration
49+
- **Documentation Site**: Expanded documentation with new features and examples
50+
51+
### 📝 Documentation
52+
- Added comprehensive MongoDB container integration guide
53+
- Enhanced getting started guide with configuration options
54+
- Direct Orbital API access documentation with examples
55+
- Mixed source format support documentation
56+
- Updated integration testing examples
57+
58+
## [0.0.3] - Previous Release
59+
60+
### Added
61+
- Core Preflight runtime and Gradle plugin
62+
- Basic Kotest integration with `OrbitalSpec`
63+
- Kafka container support for integration testing
64+
- Stubbing capabilities with `StubService`
65+
- Environment variable configuration support
66+
- Basic documentation site
67+
68+
### Fixed
69+
- Gradle plugin configuration issues
70+
- Maven publishing improvements
71+
- Version handling and dependency resolution
72+
73+
---
74+
75+
## Version Support Matrix
76+
77+
| Preflight Version | Orbital Version (Default) | Java Version | Kotlin Version |
78+
|------------------|---------------------------|--------------|----------------|
79+
| 0.0.4 | 0.36.0-M9 | 21 | 1.9.23 |
80+
| 0.0.3 | 0.36.0-M9 | 17 | 1.9.23 |
81+
| 0.0.2 | 0.36.0-M9 | 17 | 1.9.23 |
82+
83+
---
84+
85+
## Migration Guides
86+
87+
### Upgrading to 0.0.4
88+
89+
#### Java Version Requirement
90+
- **Action Required**: Update to Java 21 (previously Java 17)
91+
- Update your `JAVA_HOME` and build configuration
92+
- Use Java 21-compatible toolchains in your Gradle builds
93+
94+
#### New MongoDB Support
95+
- No breaking changes for existing Kafka-based tests
96+
- Add `ConnectorSupport.MongoDB` to your connector list if using MongoDB
97+
- Refer to the [integration testing guide](./integration-testing) for setup examples
98+
99+
#### Enhanced Configuration Options
100+
- The `preflight` extension now supports `orbitalVersion` configuration
101+
- Existing configurations continue to work without changes
102+
- Consider specifying an explicit Orbital version for reproducible builds
103+
104+
### Upgrading from 0.0.2 to 0.0.3
105+
- Updated Gradle plugin registration
106+
- Improved Maven repository configuration
107+
- No breaking API changes

‎docs/pages/index.mdx‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ You also need a `settings.gradle.kts` (but can be blank)
3636
```
3737

3838
### Configuration (Optional)
39+
40+
#### Orbital Version Configuration
3941
By default, Preflight uses Orbital version `0.36.0-M9`. You can configure which version of Orbital to test against:
4042

4143
```kotlin
@@ -50,7 +52,37 @@ preflight {
5052
}
5153
```
5254

53-
This ensures Taxi dependencies come transitively from Orbital, maintaining version compatibility.
55+
This configuration:
56+
- Ensures Taxi dependencies come transitively from Orbital, maintaining version compatibility
57+
- Enables automatic transpilation of Avro and other supported source formats
58+
- Allows testing against different Orbital API versions
59+
- Supports both release versions and milestone builds (e.g., "0.37.0-M1")
60+
61+
#### Mixed Source Support
62+
Preflight automatically handles projects with mixed source types. Your project can contain:
63+
- **Taxi schemas** (`.taxi` files)
64+
- **Avro schemas** (`.avsc` files)
65+
- **OpenAPI specifications** (`.yaml`, `.json` files)
66+
67+
All source formats are automatically transpiled to Taxi during compilation, allowing you to write unified tests regardless of your schema source format:
68+
69+
```
70+
├── src
71+
│ ├── taxi-schemas/
72+
│ │ └── user.taxi
73+
│ ├── avro-schemas/
74+
│ │ └── events.avsc
75+
│ └── openapi-specs/
76+
│ └── api.yaml
77+
├── test
78+
│ └── MixedSourcesSpec.kt
79+
```
80+
81+
The transpilation process:
82+
1. Detects all supported source formats in your project
83+
2. Converts Avro and OpenAPI schemas to Taxi equivalents
84+
3. Compiles the unified Taxi schema for testing
85+
4. Makes all types available in your test queries
5486

5587
Here's the directory structure:
5688

0 commit comments

Comments
 (0)