Astro adapter testing

[friedemannsommer]

Is there any documentation on how to test a third party Astro adapter? I seem to be unable to find it.

The only approach that i can (currently) think of is to create full astro project fixture and use the import { build, preview } from 'astro' functions to start a preview server and then send requests (via fetch or a similar HTTP client) to it.

It's probably not possible to use a virtual filesystem (like "memfs" or "mock-fs") since Vite might use bindings to native code right?

In the end i'm looking for a relatively easy and maintainable test setup, which hopefully isn't flakey.

---

For context, the adapter i want to test targets the Node.js runtime and can therefore rely on any node:* and npm module. The only limiting factor is my spare time.

[Fryuni]

There is currently no proper resource for that. Maybe it is something we should work on.

At the moment I think your best bet would be to follow what the Astro adapters that are not on the core repo do: https://github.com/withastro/adapters

There we have an @astrojs/test-utils package, but it is private. However, it is essentially a file wrapping the programmatic APIs for testing, so you can just copy the file and use it on your adapter.

For the reasons you mentioned, the tests use the real file system. Each test uses a fixture folder and tests what is generated in that folder.

[friedemannsommer]

Thanks for the hint (with the withastro/adapters repository).

I'll try to implement a first iteration based on their approach and provide an update afterwards.

[friedemannsommer]

I've got a working prototype based on your suggestion.

There were however a few obstacles i've encoutered while implementing it:

• The "astro" package doesn't export the JS API, so the imports need to use relative imports.
• Since these tests are written in TypeScript, i tried to run them via "ts-node" which doesn't work since Astro depends on the "p-limit" package which breaks it's module resolution. To workaround this issue i've used "tsx" as JIT TypeScript compiler.
• I've noticed that the preview JS API (of Astro) doesn't return the result from the actual preview implementation of the adapter. Therefore i'm unable to use 0 as port and after "start" read the resolved listening port.

Here's my (current) fixture loading implementation as reference

import { rm } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'
import type { AstroConfig, AstroInlineConfig, PreviewServer } from 'astro'
// these imports need to use a relative path since the package does not export the required files
import build from '../../../node_modules/astro/dist/core/build/index.js'
import { mergeConfig, resolveConfig } from '../../../node_modules/astro/dist/core/config/index.js'
import { preview } from '../../../node_modules/astro/dist/core/index.js'
// this is an adapter file and not relevant for the actual fixture
import type { SupportedExports } from '../../standalone.js'

// Disable telemetry
process.env.ASTRO_TELEMETRY_DISABLED = '1'

export interface AstroFixtureOptions extends AstroInlineConfig {
    // make "root" a required option
    root: string
}

export interface TestFixture {
    // ... omitted for brevity
}

const fixturesBasePath = new URL('../fixtures', import.meta.url)

export async function loadFixture(fixtureConfig: AstroFixtureOptions): Promise<TestFixture> {
    fixtureConfig.logLevel = 'silent'

    const { astroConfig } = await resolveConfig(fixtureConfig, 'dev')

    if (!astroConfig.outDir.href.startsWith(fixturesBasePath.href)) {
        throw new Error(`The fixture output "${fileURLToPath(astroConfig.outDir)}" is not in the fixtures directory`)
    }

    const resolveUrl = resolveConfigUrl(astroConfig)
    let serverRef: PreviewServer | undefined

    return {
        config: astroConfig,
        resolveUrl,
        fetch(url: URL | string, init?: RequestInit): Promise<Response> {
            return fetch(resolveUrl(url), init)
        },
        async build(overrideConfig: Partial<AstroFixtureOptions> = {}): Promise<void> {
            process.env.NODE_ENV = 'production'

            return build(mergeConfig(fixtureConfig, overrideConfig), {
                teardownCompiler: false
            })
        },
        async preview(overrideConfig: Partial<AstroFixtureOptions> = {}): Promise<PreviewServer> {
            process.env.NODE_ENV = 'production'

            const previewServer = await preview(mergeConfig(fixtureConfig, overrideConfig))

            astroConfig.server.host = previewServer.host || 'localhost'
            astroConfig.server.port = previewServer.port
            serverRef = previewServer

            return previewServer
        },
        async loadEntryPoint(): Promise<SupportedExports> {
            process.env.ASTRO_NODE_FASTIFY_INTERNAL_AUTOSTART = '0'

            return import(new URL(astroConfig.build.server, astroConfig.outDir).href) as Promise<SupportedExports>
        },
        async teardown(): Promise<void> {
            try {
                if (serverRef) {
                    await serverRef.stop()
                    await serverRef.closed()
                }
            } finally {
                await rm(astroConfig.outDir, {
                    maxRetries: 10,
                    recursive: true,
                    force: true
                })
            }
        }
    }
}

function resolveConfigUrl(config: AstroConfig): (relativeUrl: URL | string) => URL {
    return (relativeUrl: URL | string): URL => {
        return new URL(relativeUrl, `http://${config.server?.host || 'localhost'}:${config.server?.port || 4321}`)
    }
}

[friedemannsommer]

Since there is no definite answer to this question, should the discussion be left open or should I mark the reply (#8524 (comment)) of @Fryuni as answer?