testing library

Testing utilities for Trellis templates.

Provides a test engine factory, CSS-selector-based HTML matchers, snapshot golden file testing, and fragment isolation helpers.

import 'package:test/test.dart';
import 'package:trellis/testing.dart';
import 'package:trellis/trellis.dart';

void main() {
  final engine = testEngine(templates: {
    'page': '<h1 tl:text="${title}">x</h1>',
  });

  test('renders title', () {
    final html = engine.render(
      engine.loader.loadSync('page')!,
      {'title': 'Hello'},
    );
    expect(html, hasElement('h1', withText: 'Hello'));
  });
}

Properties

updateGoldens → bool

Whether golden files should be updated instead of compared.

no setter

Functions

compareOrCreateGolden(String actual, String goldenPath, {bool? update}) → void

Core golden file comparison logic. Package-private for testability.

elementCount(String selector, int count) → Matcher

Matches if exactly count elements match selector in the rendered HTML.

expectSnapshot(Trellis engine, String template, Map<String, dynamic> context, {required String goldenFile, String? fragment}) → Future<void>

Renders a template file and compares the output against a golden file.

expectSnapshotFromSource(Trellis engine, String source, Map<String, dynamic> context, {required String goldenFile, String? fragment}) → void

Renders a template source string and compares against a golden file.

hasAttribute(String selector, String attribute, dynamic value) → Matcher

Matches if an element matching selector has attribute with value.

hasElement(String selector, {String? withText, String? withAttribute, String? attributeValue, int? count}) → Matcher

Matches if rendered HTML contains element(s) matching the CSS selector.

hasNoElement(String selector) → Matcher

Matches if rendered HTML does NOT contain any element matching selector.

hasTextContent(String text) → Matcher

Matches if the rendered HTML's full text content (tags stripped) contains text.

isValidTemplate({TemplateValidator? validator}) → Matcher

Returns a matcher that validates a trellis template source string.

normalizeHtml(String html) → String

Normalizes rendered HTML for stable snapshot comparison.

testEngine({Map<String, String>? templates, bool strict = true, String prefix = 'tl', Map<String, Function>? filters, List<Processor>? processors, List<Dialect>? dialects, bool includeStandard = true, MessageSource? messageSource, String? locale}) → Trellis

Creates a Trellis engine configured for testing.

testFragment(Trellis engine, String template, String fragment, Map<String, dynamic> context) → String

Renders a specific fragment from an in-memory template.

testFragmentFile(Trellis engine, String templateName, String fragment, Map<String, dynamic> context) → Future<String>

Async version for file-based templates.