selenita

The best libraries are not only type-safe; they provide great IntelliSense. But testing IntelliSense is so cumbersome it's often ignored. selenita makes it delightful.

selenita exposes the TypeScript Language Service through a tagged-template API. Write completions, hover, and diagnostics assertions the same way you write any other test — no line/column arithmetic, no magic comment strings, no separate DSL.

---

Why test IntelliSense?

Type safety is not the whole story. When someone uses your library, TypeScript's language service is an invisible co-author — suggesting properties, flagging mistakes, explaining what each parameter means. That experience is part of your API surface.

A refactor that renames an option, changes the order of union members, or introduces a new required field can break completions silently. No runtime error. No failing test. Just a quietly degraded experience for anyone using your library.

selenita gives that surface the same regression protection you give your runtime behavior. If a completion disappears, an unexpected error appears, or two equivalent APIs start diverging — your tests catch it before your users do.

---

Highlights

• ✨ Zero arithmetic — cursors are first-class JavaScript values you interpolate directly; no line numbers, no character offsets.
• 🧩 Composable — snippet captures reusable code fragments with their own cursors; .for('alias') scopes them for multi-position use.
• 🔬 Parity testing — group + queryGroup assert that a set of APIs expose identical completions, and surface exactly what diverges when they don't.
• 📦 Mode matrix — forModes runs your tests against source, dist-esm, and dist-cjs in one declaration.
• 🏃 Synchronous — the TypeScript Language Service is synchronous. No forced await, no async test boilerplate.
• 🔒 Isolated — each test file gets its own TypeScript program. Standard concurrent mode works with zero configuration.
• 🛡️ Safe by design — invalid positions return empty results, never throw. Errors only come from programming mistakes.
• 🪝 Extensible — plain object results work with any expect. Vitest matcher addon for the best ergonomics.

---

Quick start

bun add --dev @mszr/selenita typescript   # or npm / pnpm

selenita uses globalThis.beforeAll/afterAll for lifecycle registration. Enable Vitest globals in your config:

// vitest.config.ts
export default defineConfig({ test: { globals: true } })

import { cursor, defineProject } from '@mszr/selenita'
import { describe, expect, it } from 'vitest'

const project = defineProject({ tsconfig: './tsconfig.json' })

describe('createQuery', () => {
  it('suggests option keys', () => {
    const { completions } = project.query`
      import { createQuery } from './src'
      createQuery({ ${cursor} })
    `
    expect(completions).toContain('table')
    expect(completions).toContain('limit')
  })

  it('flags unknown options as errors', () => {
    const { errors } = project.check`
      import { createQuery } from './src'
      createQuery({ tabel: 'users' })
    `
    expect(errors.length).toBeGreaterThan(0)
  })
})

---

Complete example

import { cursor, defineProject, group, snippet } from '@mszr/selenita'
import { describe, expect, it } from 'vitest'
import '@mszr/selenita/vitest'

const project = defineProject({
  tsconfig: './tsconfig.json',
  aliases: { '#fixtures/*': './tests/fixtures/*' },
})

const queryApis = group('queryApis', ['db.findMany', 'db.findOne', 'db.aggregate'])
const filterArg = snippet`{ status: 'open', ${cursor('filter')} }`

// ─── option completions ───────────────────────────────────────────

describe('createQuery', () => {
  it('suggests all options', () => {
    const { completions } = project.query`
      import { createQuery } from './src'
      createQuery({ ${cursor} })
    `
    expect(completions).toContainCompletions(['table', 'limit', 'orderBy'])
    expect(completions).not.toContainCompletion('tabel')
  })

  it('table is a required string property', () => {
    const result = project.query`
      import { createQuery } from './src'
      createQuery({ ${cursor} })
    `
    expect(result.completionItem('table')).toHaveKind('property')
    expect(result.completionItem('table')).toHaveType('string')
    expect(result.completionItem('table')).not.toBeDeprecated()
  })

  it('completions narrow as options fill in', () => {
    const result = project.query`
      import { createQuery } from './src'
      createQuery({ ${cursor('empty')} })
      createQuery({ table: 'users', ${cursor('partial')} })
    `
    expect(result.at('empty').completions).toContainCompletion('table')
    expect(result.at('partial').completions).not.toContainCompletion('table')
  })
})

// ─── API parity ───────────────────────────────────────────────────

describe('query API parity', () => {
  it('all query methods expose identical filter completions', () => {
    const result = project.queryGroup(queryApis, api => snippet`${api}(${filterArg})`)`
      import { db } from '#fixtures/db'
    `
    expect(result.group.at('filter')).toHaveCompletionParity()
  })
})

// ─── dist output ─────────────────────────────────────────────────

describe('dist output', () => {
  project.forModes(
    {
      'source': './src/index.ts',
      'dist-esm': { entry: './dist/index.js', dts: './dist/index.d.ts' },
    },
    (project, mode) => {
      it(`[${mode}] completions survive compilation`, () => {
        const { completions } = project.query`
          import { createQuery } from '${project.entry}'
          createQuery({ ${cursor} })
        `
        expect(completions).toContainCompletion('table')
      })
    }
  )
})

---

Documentation

Getting started [get raw]	Installation, project setup, connecting to your tsconfig
Querying [get raw]	project.query, project.check, all result shapes
Snippets [get raw]	Reusable fragments, .for() scoping, composition
Groups & parity [get raw]	group, project.queryGroup, hasParity, divergence
Project config [get raw]	project.with(), project.forModes(), escape hatches
Matchers [get raw]	All custom Vitest matchers with examples