Skip to content

README.md

Latest commit

 

History

History
131 lines (92 loc) · 3.94 KB

README.md

File metadata and controls

131 lines (92 loc) · 3.94 KB

Manifest Snapshot Tests

This directory contains snapshot tests that compare the Dart builder's output with the Node.js Firebase Functions SDK to ensure compatibility.

Overview

The snapshot tests verify that the Dart Firebase Functions builder generates deployment manifests that are structurally compatible with the Node.js SDK. This ensures that functions deployed using the Dart runtime will work correctly with the Firebase CLI and Cloud Functions platform.

Test Setup

Reference Implementation

Node.js Example: test/fixtures/nodejs_reference/

  • Contains equivalent functions written in Node.js
  • Manifest extracted via firebase-functions HTTP endpoint
  • Saved as nodejs_manifest.json for comparison

Dart Example: test/fixtures/dart_reference/

  • Contains equivalent functions written in Dart
  • Manifest generated by builder at functions.yaml

Running the Tests

# Run snapshot tests
dart test test/snapshots/manifest_snapshot_test.dart

# Run with detailed output
dart test test/snapshots/manifest_snapshot_test.dart --reporter=expanded

Updating the Reference Snapshot

When the Node.js SDK is updated or the example functions change, regenerate the reference manifest:

cd test/fixtures/nodejs_reference

# Start firebase-functions with control API enabled
GCLOUD_PROJECT="test-project" \
PORT="8080" \
FUNCTIONS_CONTROL_API="true" \
npx firebase-functions &

# Wait for server to start, then fetch manifest
sleep 3
curl -s http://localhost:8080/__/functions.yaml | python3 -m json.tool > nodejs_manifest.json

# Stop the server
pkill -f firebase-functions

Test Coverage

The snapshot tests verify:

  • Spec Version: Both use v1alpha1
  • Function Discovery: Same number and types of endpoints
  • HTTPS Functions: onRequest and onCall structure
  • Pub/Sub Functions: Event trigger format and naming
  • Trigger Configurations: Proper trigger types for each function
  • Platform Identifier: Both use gcfv2

Key Differences

Dart-Specific Features

  • Region field: Dart includes default region (us-central1)
  • Required APIs: Dart lists cloudfunctions.googleapis.com
  • Null fields: Dart omits null/default values for cleaner YAML

Node.js-Specific Features

  • Null fields: Explicitly includes all fields with null values
  • Empty objects: Includes empty labels: {} and extensions: {}
  • VPC field: Single vpc field vs Dart's vpcConnector + vpcConnectorEgressSettings

Fixed Issues

Pub/Sub Topic Naming

Issue: Topic names with hyphens were preserved in function names, causing inconsistency.

Solution: Sanitize topic names by replacing hyphens with underscores in function names:

  • Topic: my-topic
  • Function name: onMessagePublished_my_topic
  • Event filter: {topic: "my-topic"} (original name preserved)

Pub/Sub Event Structure

Issue: Dart was using legacy resource format instead of v2 eventFilters.

Solution: Updated to match Node.js v2 API:

eventTrigger:
  eventType: "google.cloud.pubsub.topic.v1.messagePublished"
  eventFilters:
    topic: "my-topic"
  retry: false

Retry Field

Issue: Missing retry field on event triggers.

Solution: Added retry: false as default for Pub/Sub triggers.

Continuous Integration

These tests should run on every commit to ensure:

  • Builder changes don't break compatibility
  • New trigger types match Node.js structure
  • Options are correctly serialized

Add to CI pipeline:

- name: Run Snapshot Tests
  run: |
    cd firebase-functions-dart
    dart pub upgrade
    dart run build_runner build
    dart test test/snapshots/

Future Enhancements

  • Add snapshot tests for all trigger types (Firestore, Storage, Auth, Scheduler)
  • Test options extraction (memory, CPU, regions, etc.)
  • Test parameter and expression serialization
  • Validate against firebase-tools deployment schemas
  • Add performance benchmarks (build time, manifest size)