# Introducing Orbital Preflight

> We've released a new unit and integration testing framework

Source: https://orbitalhq.com/blog/2025-06-26-announcing-orbital-preflight
Date: 2025-06-26

Today we're announcing the first release of [Preflight](https://github.com/orbitalapi/preflight), our unit and integration testing framework for Taxi and Orbital projects.

Over the past few years, we've been amazed by the creative ways our community has used Taxi. The expression engine and [Expression Types](https://taxilang.org/docs/taxiql/expressions-traversal#expression-types) have grown 
to support increasingly rich business logic-directly in the data gateway.

For example:

**Calculating values with a when block**

Schema:

```taxi
import taxi.stdlib.dates.currentDate

type ReleaseDate inherits Date
type FilmId inherits String
type FilmTitle inherits String
type FilmRating inherits String

enum ChildrenRatings {
  G,
  PG,
  PG13
}

closed model Film {
  id : FilmId
  title : FilmTitle
  rating : FilmRating
  releaseDate : ReleaseDate
}

//@docs:highlightStart
type ChildFriendlyMovie inherits String = (ReleaseDate, FilmRating) ->
  when {
    ReleaseDate < currentDate() &&
            ChildrenRatings.hasEnumNamed(FilmRating) -> "Bring the kids"
    else -> "Save it for date night"
  }
//@docs:highlightEnd

service FilmService {
  operation getFilms(): Film[]
}
```

Query:

```taxi
find { Film[] } as {
    title : FilmTitle
    rating : FilmRating
    releaseDate : ReleaseDate
    childFriendly : ChildFriendlyMovie
}[]
```

As Taxi has evolved to support more embedded business logic, the ecosystem has lacked a proper unit testing framework. Today, we're closing that gap with the launch of Preflight!

Preflight is a thin wrapper around the same testing tools the Orbital team has relied on for years. While we're releasing today on version `0.0.3`, the framework itself is already mature and battle-tested.

Preflight tests are written in Kotlin - the underlying language powering Taxi and Orbital - rather than Taxi itself.

## Getting started

To get started, just drop a `build.gradle.kts` file into your Taxi project:

```kotlin
// build.gradle.kts
plugins {
    kotlin("jvm") version "1.9.23"
    id("com.orbitalhq.preflight") version "0.0.3" // Use the latest version
}
```

In IntelliJ, your project will be automatically configured with the appropriate test folder. If you install the [Kotest IntelliJ Plugin](https://kotest.io/docs/intellij/intellij-plugin.html), you'll also see gutter icons for running your tests directly from the IDE.

## Writing tests

Preflight includes:

* A custom Kotest Spec class (`OrbitalSpec`), which:

* Detects and compiles your Taxi project
* Provides access to your source code, compiled project, and the Orbital schema
* A DSL for [stubbing responses](https://preflight.orbitalhq.com/stubbing)
* A low-level [Kotest Extension](https://github.com/orbitalapi/preflight/blob/main/preflight-core/preflight-runtime/src/main/kotlin/com/orbitalhq/preflight/dsl/PreflightExtension.kt), if you want to embed Preflight into your own build system

```kotlin
// test/HelloWorldSpec.kt
import com.orbitalhq.preflight.dsl.OrbitalSpec
import io.kotest.matchers.shouldBe

class HelloWorldSpec : OrbitalSpec({
    describe("First test") {
        it("should perform a simple assertion") {
              """find { 1 + 2 }""".queryForScalar()
                .shouldBe(3)
        }
    }
})
```

## Running tests

Running tests is fast and CI-friendly. Just use Gradle from the root of your Taxi project:

```
./gradlew test
```

This will:

* Detect your Taxi project via `taxi.conf`
* Compile it, including dependencies and source transformations (like Avro or OpenAPI)
* Execute your test suite

🚀🟢 Boom! Green builds all around.

## 🐛 Debugging
When you're running tests, you have access to the full TaxiQL query engine inside your JVM. This means you can set breakpoints,
and inspect.

By using Preflight's `.queryForTypedInstance()` methods, you can access Orbital's internal state, and poke around.

This includes access to the full data lineage for every attribute, right in your debugger, which let's you trace back
where every field and value came from.

## Playground integration

When a test fails, the failure message includes a link to a reproducible scenario in [Taxi Playground](https://playground.taxilang.org). This makes it easy to debug or share with others-Playground links are now a common way users report issues to the Orbital team.

## Join in

Like [Orbital](https://github.com/orbitalapi/orbital) and [Taxi](https://github.com/taxilang/taxilang), Preflight is fully open source under the Apache 2.0 license.

Try it out, and come say hi in our [Slack](https://join.slack.com/t/orbitalapi/shared_invite/zt-697laanr-DHGXXak5slqsY9DqwrkzHg). We'd love your feedback.