princesseuh / astro-component-tester

Utility to test Astro components

astro-component-tester

Utility to help you write tests for your Astro components. In essence, what it does is create a temporary empty Astro project with only the selected component in a src/pages/index.astro file, then it builds it using the Astro CLI and finally, it returns the output of that build

While it's intended to be used when writing tests, you could also use it outside of that usecase, for instance to build a single component 😄

Part of astro-component-template

Usage

Examples below uses Mocha and Chai for convenience but this should work with any tools

import { expect } from 'chai';
import { getComponentOutput } from 'astro-component-tester';

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

  // Component content here is equal to simply <div>Hello</div>
  before(async () => {
    component = await getComponentOutput('./src/Component.astro');
  });

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

You can also pass props to the component, using the following method:

Component

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

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

Test

import { expect } from 'chai';
import { getComponentOutput } from '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);
  });
});

Through a third parameter to getComponentOutput, it's possible to pass settings to the build operation, this is also how you can pass options to Astro itself, for instance, to test the output of a component that uses a Svelte component:

import { expect } from 'chai';
import { getComponentOutput } from '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

Since this work by building the component in an isolated environment, any variables depending on a specific context will be lost. For instance, Astro.request will always return the index page. Presumably, if you're building a component that should work in any instance, this wouldn't be an issue but it could become one for some components.

At the moment, astro-component-tester does not support any kind of mocking for supporting that use case

astro-component-tester's Issues

Support `Astro 3`

 WARN  Issues with peer dependencies found
.
└─┬ astro-component-tester 0.6.0
└── ✕ unmet peer astro@^1.0.0-rc.1: found 3.3.4

Enhancement Proposal: Mocking Capabilities for Context-Specific Variables within Isolated Component Testing

Dear Contributors,

I hope this message finds you well. I am writing to propose an enhancement to the astro-component-tester utility, which I have found to be an invaluable tool in the development of Astro components. The utility's ability to create an isolated testing environment is commendable; however, I have encountered a limitation that I believe could be addressed to further refine the testing experience.

Issue Description

The current implementation of astro-component-tester constructs an isolated environment for building components, which, while effective for most scenarios, does not account for context-specific variables such as Astro.request. This limitation becomes apparent when attempting to test components that rely on such context for their functionality. The absence of a mocking mechanism for these variables means that certain component behaviours cannot be accurately tested or replicated.

Proposed Solution

To enhance the utility's testing capabilities, I propose the introduction of a mocking framework that allows developers to simulate context-specific variables. This would enable a more comprehensive testing environment that can mimic the various states and conditions a component might encounter in a production setting.

Potential Implementation

A potential approach to this could involve:

• Extending the getComponentOutput function to accept an additional parameter for context mocks.
• Implementing a simple key-value mapping that the build process can utilise to replace context-specific variables with developer-provided mock data.
• Providing documentation and examples on how to effectively use the mocking feature to simulate different scenarios.

Benefits

The inclusion of a mocking feature would provide several benefits:

• It would allow for more thorough testing of components that depend on global context variables.
• It would increase the confidence in the component's behaviour across different use cases.
• It would align astro-component-tester with other testing frameworks that offer similar mocking capabilities, thereby enhancing its utility.

I am keen to hear your thoughts on this proposal and would be delighted to contribute to the implementation should there be consensus on its potential value.

Thank you for considering this enhancement. I look forward to a fruitful discussion.

Best regards,
yihong1120

Full support for Astro's newer features

While the project currently does work on all versions of Astro, some features are not supported. For instance, it is not possible to add integrations.

Write docs

This is missing documentation at the moment. I'd like to provide something similar to the Docs.md file available in my other projects, ex: https://github.com/Princesseuh/astro-eleventy-img/blob/main/Docs.md