@advastro/astro-component-tester

A lightweight utility that builds an Astro component in a temporary project and returns its rendered HTML. Ideal for testing, debugging, or quickly inspecting a single component.

This package is a modernized fork of the original astro-component-tester component.

Why?

Astro components often rely on the full Astro build pipeline. Traditional test setups struggle with this, so this tool spins up a minimal Astro project, builds your component in isolation, and gives you the exact output Astro would produce.

Installation

npm install @advastro/astro-component-tester
# or
yarn add @advastro/astro-component-tester
# or
pnpm install @advastro/astro-component-tester
# or
bun install @advastro/astro-component-tester

Use

Examples below use Mocha and Chai, but any test framework works.

import { expect } from 'chai'
import { getComponentOutput } from '@advastro/astro-component-tester'

describe('Component', async () => {
  let component

  before(async () => {
    component = await getComponentOutput('./src/Component.astro')
  })

  it('example component should say hello', () => {
    expect(component.html).to.contain('Hello')
  })
})

Passing Props

Component:

---
const { mySuperProp } = Astro.props
---

<div>{ mySuperProp + 1 }</div>

Test:

import { expect } from 'chai'
import { getComponentOutput } from '@advastro/astro-component-tester'

describe('Component', async () => {
  let component

  before(async () => {
    component = await getComponentOutput('./src/Component.astro', { mySuperProp: 1 })
  })

  it('example component should return 2', () => {
    expect(component.html).to.contain(2)
  })
})

Passing Astro Options

Useful when testing components that rely on specific renderers:

import { expect } from 'chai'
import { getComponentOutput } from '@advastro/astro-component-tester'

describe('Component', async () => {
  let component

  before(async () => {
    component = await getComponentOutput('./src/Component.astro', {}, { astroOptions: { renderers: ['@astrojs/renderer-svelte'] } })
  })

  it('example component should say hello using a Svelte component', () => {
    expect(component.html).to.contain('Hello from Svelte')
  })
})

Limitations

Context-specific variables

Components are built in an isolated environment. Context-dependent values (e.g. Astro.request ) will not reflect real routing or page state. Mocking such values is currently not supported.

Links

• License (MIT)
• Website