Ponte al día con lo más destacado de Firebase en Google I/O 2023. Más información

Esta página se ha traducido con Cloud Translation API.

Construir pruebas unitarias

Firebase Local Emulator Suite facilita la validación completa de las funciones y el comportamiento de tu aplicación. También es una gran herramienta para verificar las configuraciones de las reglas de seguridad de Firebase. Utilice los emuladores de Firebase para ejecutar y automatizar pruebas unitarias en un entorno local. Los métodos descritos en este documento deberían ayudarle a crear y automatizar pruebas unitarias para su aplicación que validen sus reglas.

Si aún no lo has hecho, configura los emuladores de Firebase .

Antes de ejecutar el emulador

Antes de comenzar a utilizar el emulador, tenga en cuenta lo siguiente:

El emulador cargará inicialmente las reglas especificadas en el campo firestore.rules o 'storage.rules' de su archivo firebase.json . Si el archivo no existe y no utiliza el método loadFirestoreRules o 'loadStorageRules' como se describe a continuación, el emulador trata todos los proyectos como si tuvieran reglas abiertas.
Si bien la mayoría de los SDK de Firebase funcionan directamente con los emuladores, solo la biblioteca @firebase/rules-unit-testing admite auth simulada en las reglas de seguridad, lo que facilita mucho las pruebas unitarias. Además, la biblioteca admite algunas funciones específicas del emulador, como borrar todos los datos, como se enumera a continuación.
Los emuladores también aceptarán tokens de Firebase Auth de producción proporcionados a través de los SDK del cliente y evaluarán las reglas en consecuencia, lo que permite conectar su aplicación directamente a los emuladores en pruebas de integración y manuales.

Diferencias entre los emuladores de bases de datos y los de producción.

No es necesario crear explícitamente una instancia de base de datos. El emulador creará automáticamente cualquier instancia de base de datos a la que se acceda.
Cada nueva base de datos se inicia con reglas cerradas, por lo que los usuarios que no sean administradores no podrán leer ni escribir.
Cada base de datos emulada aplica los límites y cuotas del plan Spark (en particular, esto limita cada instancia a 100 conexiones simultáneas).
Cualquier base de datos aceptará la cadena "owner" como token de autenticación de administrador.
Actualmente, los emuladores no tienen interacciones funcionales con otros productos de Firebase. En particular, el flujo normal de autenticación de Firebase no funciona. En su lugar, puede utilizar el método initializeTestApp() en la biblioteca rules-unit-testing , que requiere un campo auth . El objeto de Firebase creado con este método se comporta como si se hubiera autenticado correctamente como cualquier entidad que usted proporcione. Si pasa null , se comportará como un usuario no autenticado (las reglas auth != null fallarán, por ejemplo).

Interactuar con el emulador de base de datos en tiempo real

Se puede acceder a una instancia de producción de Firebase Realtime Database en un subdominio de firebaseio.com y puede acceder a la API REST de esta manera:

https://<database_name>.firebaseio.com/path/to/my/data.json

El emulador se ejecuta localmente y está disponible en localhost:9000 . Para interactuar con una instancia de base de datos específica, deberá usar el parámetro de consulta ns para especificar el nombre de la base de datos.

http://localhost:9000/path/to/my/data.json?ns=<database_name>

Ejecute pruebas unitarias locales con la versión 9 del SDK de JavaScript

Firebase distribuye una biblioteca de pruebas unitarias de reglas de seguridad con su SDK de JavaScript versión 9 y su SDK versión 8. Las API de la biblioteca son significativamente diferentes. Recomendamos la biblioteca de pruebas v9, que es más optimizada y requiere menos configuración para conectarse a emuladores y así evitar de forma segura el uso accidental de recursos de producción. Para lograr compatibilidad con versiones anteriores, seguimos poniendo a disposición la biblioteca de pruebas v8 .

Métodos de prueba comunes y funciones de utilidad en el SDK v9
Métodos de prueba específicos del emulador en el SDK v9

Utilice el módulo @firebase/rules-unit-testing para interactuar con el emulador que se ejecuta localmente. Si obtiene tiempos de espera o errores ECONNREFUSED , verifique que el emulador realmente se esté ejecutando.

Recomendamos encarecidamente utilizar una versión reciente de Node.js para poder utilizar la notación async/await . Casi todo el comportamiento que quizás desee probar involucra funciones asincrónicas y el módulo de prueba está diseñado para funcionar con código basado en Promise.

La biblioteca de pruebas unitarias de reglas v9 siempre está al tanto de los emuladores y nunca toca sus recursos de producción.

Importa la biblioteca utilizando declaraciones de importación modulares v9. Por ejemplo:

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment
} from "@firebase/rules-unit-testing"

// Use `const { … } = require("@firebase/rules-unit-testing")` if imports are not supported
// Or we suggest `const testing = require("@firebase/rules-unit-testing")` if necessary.

Una vez importadas, la implementación de pruebas unitarias implica:

Crear y configurar un RulesTestEnvironment con una llamada a initializeTestEnvironment .
Configurar datos de prueba sin activar reglas, utilizando un método conveniente que le permite omitirlas temporalmente, RulesTestEnvironment.withSecurityRulesDisabled .
Configurar un conjunto de pruebas y enlaces antes/después de cada prueba con llamadas para limpiar los datos y el entorno de la prueba, como RulesTestEnvironment.cleanup() o RulesTestEnvironment.clearFirestore() .
Implementar casos de prueba que imitan los estados de autenticación usando RulesTestEnvironment.authenticatedContext y RulesTestEnvironment.unauthenticatedContext .

Métodos comunes y funciones de utilidad.

Consulte también los métodos de prueba específicos del emulador utilizando la API modular .

initializeTestEnvironment() => RulesTestEnvironment

Esta función inicializa un entorno de prueba para pruebas unitarias de reglas. Llame a esta función primero para la configuración de la prueba. La ejecución exitosa requiere que se estén ejecutando emuladores.

La función acepta un objeto opcional que define TestEnvironmentConfig , que puede consistir en un ID de proyecto y ajustes de configuración del emulador.

let testEnv = await initializeTestEnvironment({
  projectId: "demo-project-1234",
  firestore: {
    rules: fs.readFileSync("firestore.rules", "utf8"),
  },
});

Nota: Los emuladores conservan los datos entre invocaciones de prueba en una única ejecución del emulador. Esto podría afectar sus resultados. Para borrar datos entre cada ejecución de prueba, llame al método de borrado de datos del emulador correspondiente, por ejemplo, clearFirestoreData , entre pruebas.

RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext

Este método crea un RulesTestContext , que se comporta como un usuario de autenticación autenticado. Las solicitudes creadas a través del contexto devuelto tendrán adjunto un token de autenticación simulado. Opcionalmente, pase un objeto que defina notificaciones personalizadas o anulaciones para las cargas útiles del token de autenticación.

Utilice el objeto de contexto de prueba devuelto en sus pruebas para acceder a cualquier instancia del emulador configurada, incluidas aquellas configuradas con initializeTestEnvironment .

// Assuming a Firestore app and the Firestore emulator for this example
import { setDoc } from "firebase/firestore";

const alice = testEnv.authenticatedContext("alice", { … });
// Use the Firestore instance associated with this context
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

RulesTestEnvironment.unauthenticatedContext() => RulesTestContext

Este método crea un RulesTestContext , que se comporta como un cliente que no ha iniciado sesión mediante autenticación. Las solicitudes creadas a través del contexto devuelto no tendrán tokens de autenticación de Firebase adjuntos.

Utilice el objeto de contexto de prueba devuelto en sus pruebas para acceder a cualquier instancia del emulador configurada, incluidas aquellas configuradas con initializeTestEnvironment .

// Assuming a Cloud Storage app and the Storage emulator for this example
import { getStorage, ref, deleteObject } from "firebase/storage";

const alice = testEnv.unauthenticatedContext();

// Use the Cloud Storage instance associated with this context
const desertRef = ref(alice.storage(), 'images/desert.jpg');
await assertSucceeds(deleteObject(desertRef));

RulesTestEnvironment.withSecurityRulesDisabled()

Ejecute una función de configuración de prueba con un contexto que se comporte como si las reglas de seguridad estuvieran deshabilitadas.

Este método toma una función de devolución de llamada, que toma el contexto de omisión de reglas de seguridad y devuelve una promesa. El contexto se destruirá una vez que la promesa se resuelva/rechace.

RulesTestEnvironment.cleanup()

Este método destruye todos los RulesTestContexts creados en el entorno de prueba y limpia los recursos subyacentes, lo que permite una salida limpia.

Este método no cambia el estado de los emuladores de ninguna manera. Para restablecer datos entre pruebas, utilice el método de borrar datos específico del emulador de aplicaciones.

assertSucceeds(pr: Promise<any>)) => Promise<any>

Esta es una función de utilidad de caso de prueba.

La función afirma que la Promesa proporcionada que envuelve una operación del emulador se resolverá sin violaciones de las reglas de seguridad.

await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

assertFails(pr: Promise<any>)) => Promise<any>

Esta es una función de utilidad de caso de prueba.

La función afirma que la Promesa proporcionada que envuelve una operación del emulador será rechazada con una violación de las Reglas de Seguridad.

await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });

Métodos específicos del emulador

Consulte también métodos de prueba comunes y funciones de utilidad utilizando la API modular .

Tienda de fuego en la nube

RulesTestEnvironment.clearFirestore() => Promise<void>

Este método borra los datos de la base de datos de Firestore que pertenecen al projectId configurado para el emulador de Firestore.

RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;

Este método obtiene una instancia de Firestore para este contexto de prueba. La instancia del SDK del cliente Firebase JS devuelta se puede usar con las API del SDK del cliente (v9 modular o compatible con v9).

Base de datos en tiempo real

RulesTestEnvironment.clearDatabase() => Promise<void>

Este método borra los datos de Realtime Database que pertenecen al projectId configurado para el emulador de Realtime Database.

RulesTestContext.database(databaseURL?: Firestore.FirestoreSettings) => Firestore;

Obtenga una instancia de Realtime Database para este contexto de prueba. La instancia del SDK del cliente Firebase JS devuelta se puede usar con las API del SDK del cliente (modulares o con espacio de nombres, versión 9 o superior). El método acepta una URL de la instancia de Realtime Database. Si se especifica, devuelve una instancia para una versión emulada del espacio de nombres con parámetros extraídos de la URL.

Almacenamiento en la nube

RulesTestEnvironment.clearStorage() => Promise<void>

Este método borra objetos y metadatos en depósitos de almacenamiento que pertenecen al projectId configurado para el emulador de Cloud Storage.

RulesTestContext.storage(bucketUrl?: string) => Firebase Storage;

Este método devuelve una instancia de almacenamiento configurada para conectarse al emulador. El método acepta una URL gs:// al Firebase Storage Bucket para realizar pruebas. Si se especifica, devuelve una instancia de almacenamiento para una versión emulada del nombre del depósito.

Ejecute pruebas de unidades locales con el SDK de JavaScript v8

Seleccione un producto para ver los métodos utilizados por el SDK de prueba de Firebase para interactuar con el emulador.

Tienda de fuego en la nube

initializeTestApp({ projectId: string, auth: Object }) => FirebaseApp

Este método devuelve una aplicación Firebase inicializada correspondiente al ID del proyecto y la variable de autenticación especificada en las opciones. Úselo para crear una aplicación autenticada como un usuario específico para usar en las pruebas.

firebase.initializeTestApp({
  projectId: "my-test-project",
  auth: { uid: "alice", email: "alice@example.com" }
});

Nota: El emulador de Cloud Firestore conserva los datos entre invocaciones de prueba en una única ejecución del emulador. Esto podría afectar sus resultados. Para borrar datos entre cada ejecución de prueba, llame al método clearFirestoreData entre pruebas.

initializeAdminApp({ projectId: string }) => FirebaseApp

Este método devuelve una aplicación Firebase de administrador inicializada. Esta aplicación pasa por alto las reglas de seguridad al realizar lecturas y escrituras. Úselo para crear una aplicación autenticada como administrador para establecer el estado de las pruebas.

firebase.initializeAdminApp({ projectId: "my-test-project" });

apps() => [FirebaseApp] Este método devuelve todas las aplicaciones de prueba y administración actualmente inicializadas. Úselo para limpiar aplicaciones entre o después de las pruebas.

Promise.all(firebase.apps().map(app => app.delete()))

loadFirestoreRules({ projectId: string, rules: Object }) => Promise

Este método envía reglas a una base de datos que se ejecuta localmente. Toma un objeto que especifica las reglas como una cadena. Utilice este método para establecer las reglas de su base de datos.

firebase.loadFirestoreRules({
  projectId: "my-test-project",
  rules: fs.readFileSync("/path/to/firestore.rules", "utf8")
});

assertFails(pr: Promise) => Promise

Este método devuelve una promesa que se rechaza si la entrada se realiza correctamente o si la entrada se rechaza. Utilice esto para afirmar si falla la lectura o escritura de una base de datos.

firebase.assertFails(app.firestore().collection("private").doc("super-secret-document").get());

assertSucceeds(pr: Promise) => Promise

Este método devuelve una promesa que tiene éxito si la entrada tiene éxito y se rechaza si se rechaza la entrada. Utilice esto para afirmar si la lectura o escritura de una base de datos se realizó correctamente.

firebase.assertSucceeds(app.firestore().collection("public").doc("test-document").get());

clearFirestoreData({ projectId: string }) => Promise

Este método borra todos los datos asociados con un proyecto particular en la instancia de Firestore que se ejecuta localmente. Utilice este método para limpiar después de las pruebas.

firebase.clearFirestoreData({
  projectId: "my-test-project"
});

Base de datos en tiempo real

initializeTestApp({ databaseName: string, auth: Object }) => FirebaseApp

Úselo para crear una aplicación autenticada como un usuario específico para usar en las pruebas.

Devuelve una aplicación de Firebase inicializada correspondiente al nombre de la base de datos y la anulación de la variable de autenticación especificada en las opciones.

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

initializeAdminApp({ databaseName: string }) => FirebaseApp

Úselo para crear una aplicación autenticada como administrador para configurar el estado de las pruebas.

Devuelve una aplicación de administrador de Firebase inicializada correspondiente al nombre de la base de datos especificado en las opciones. Esta aplicación pasa por alto las reglas de seguridad al leer y escribir en la base de datos.

firebase.initializeAdminApp({ databaseName: "my-database" });

loadDatabaseRules({ databaseName: string, rules: Object }) => Promise

Utilice esto para establecer las reglas de su base de datos.

Envía reglas a una base de datos que se ejecuta localmente. Toma un objeto de opciones que especifica su "nombre de base de datos" y sus "reglas" como cadenas.

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

apps() => [FirebaseApp]

Devuelve todas las aplicaciones de prueba y administración actualmente inicializadas.

Use esto para limpiar aplicaciones entre o después de las pruebas (tenga en cuenta que las aplicaciones inicializadas con oyentes activos impiden que JavaScript salga):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Devuelve una promesa que se rechaza si la entrada se realiza correctamente y tiene éxito si se rechaza la entrada.

Utilice esto para afirmar que falla la lectura o escritura de una base de datos:

firebase.assertFails(app.database().ref("secret").once("value"));

assertSucceeds(pr: Promise) => Promise

Devuelve una promesa que tiene éxito si la entrada tiene éxito y se rechaza si se rechaza la entrada.

Utilice esto para afirmar que la lectura o escritura de una base de datos se realiza correctamente:

firebase.assertSucceeds(app.database().ref("public").once("value"));

Almacenamiento en la nube

initializeTestApp({ storageBucket: string, auth: Object }) => FirebaseApp

Úselo para crear una aplicación autenticada como un usuario específico para usar en las pruebas.

Devuelve una aplicación de Firebase inicializada correspondiente al nombre del depósito de almacenamiento y la anulación de la variable de autenticación especificada en las opciones.

firebase.initializeTestApp({
  storageBucket: "my-bucket",
  auth: { uid: "alice" }
});

initializeAdminApp({ storageBucket: string }) => FirebaseApp

Úselo para crear una aplicación autenticada como administrador para configurar el estado de las pruebas.

Devuelve una aplicación de administrador de Firebase inicializada correspondiente al nombre del depósito de almacenamiento especificado en las opciones. Esta aplicación pasa por alto las reglas de seguridad al leer y escribir en el depósito.

firebase.initializeAdminApp({ storageBucket: "my-bucket" });

loadStorageRules({ storageBucket: string, rules: Object }) => Promise

Úselo para establecer las reglas de su depósito de almacenamiento.

Envía reglas a depósitos de almacenamiento administrados localmente. Toma un objeto de opciones que especifica su "storageBucket" y sus "reglas" como cadenas.

firebase
      .loadStorageRules({
        storageBucket: "my-bucket",
        rules: fs.readFileSync("/path/to/storage.rules", "utf8")
      });

apps() => [FirebaseApp]

Devuelve todas las aplicaciones de prueba y administración actualmente inicializadas.

Use esto para limpiar aplicaciones entre o después de las pruebas (tenga en cuenta que las aplicaciones inicializadas con oyentes activos impiden que JavaScript salga):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Devuelve una promesa que se rechaza si la entrada se realiza correctamente y tiene éxito si se rechaza la entrada.

Utilice esto para afirmar que falla la lectura o escritura de un depósito de almacenamiento:

firebase.assertFails(app.storage().ref("letters/private.doc").getMetadata());

assertSucceeds(pr: Promise) => Promise

Devuelve una promesa que tiene éxito si la entrada tiene éxito y se rechaza si se rechaza la entrada.

Utilice esto para afirmar que la lectura o escritura de un depósito de almacenamiento se realizó correctamente:

firebase.assertFails(app.storage().ref("images/cat.png").getMetadata());

API de biblioteca RUT para JS SDK v8

Seleccione un producto para ver los métodos utilizados por el SDK de prueba de Firebase para interactuar con el emulador.

Tienda de fuego en la nube

initializeTestApp({ projectId: string, auth: Object }) => FirebaseApp

firebase.initializeTestApp({
  projectId: "my-test-project",
  auth: { uid: "alice", email: "alice@example.com" }
});

initializeAdminApp({ projectId: string }) => FirebaseApp

firebase.initializeAdminApp({ projectId: "my-test-project" });

apps() => [FirebaseApp] Este método devuelve todas las aplicaciones de prueba y administración actualmente inicializadas. Úselo para limpiar aplicaciones entre o después de las pruebas.

Promise.all(firebase.apps().map(app => app.delete()))

loadFirestoreRules({ projectId: string, rules: Object }) => Promise

firebase.loadFirestoreRules({
  projectId: "my-test-project",
  rules: fs.readFileSync("/path/to/firestore.rules", "utf8")
});

assertFails(pr: Promise) => Promise

Este método devuelve una promesa que se rechaza si la entrada se realiza correctamente o si la entrada se rechaza. Utilice esto para afirmar si falla la lectura o escritura de una base de datos.

firebase.assertFails(app.firestore().collection("private").doc("super-secret-document").get());

assertSucceeds(pr: Promise) => Promise

firebase.assertSucceeds(app.firestore().collection("public").doc("test-document").get());

clearFirestoreData({ projectId: string }) => Promise

Este método borra todos los datos asociados con un proyecto particular en la instancia de Firestore que se ejecuta localmente. Utilice este método para limpiar después de las pruebas.

firebase.clearFirestoreData({
  projectId: "my-test-project"
});

Base de datos en tiempo real

initializeTestApp({ databaseName: string, auth: Object }) => FirebaseApp

Úselo para crear una aplicación autenticada como un usuario específico para usar en las pruebas.

Devuelve una aplicación de Firebase inicializada correspondiente al nombre de la base de datos y la anulación de la variable de autenticación especificada en las opciones.

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

initializeAdminApp({ databaseName: string }) => FirebaseApp

Úselo para crear una aplicación autenticada como administrador para configurar el estado de las pruebas.

firebase.initializeAdminApp({ databaseName: "my-database" });

loadDatabaseRules({ databaseName: string, rules: Object }) => Promise

Utilice esto para establecer las reglas de su base de datos.

Envía reglas a una base de datos que se ejecuta localmente. Toma un objeto de opciones que especifica su "nombre de base de datos" y sus "reglas" como cadenas.

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

apps() => [FirebaseApp]

Devuelve todas las aplicaciones de prueba y administración actualmente inicializadas.

Use esto para limpiar aplicaciones entre o después de las pruebas (tenga en cuenta que las aplicaciones inicializadas con oyentes activos impiden que JavaScript salga):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Devuelve una promesa que se rechaza si la entrada se realiza correctamente y tiene éxito si se rechaza la entrada.

Utilice esto para afirmar que falla la lectura o escritura de una base de datos:

firebase.assertFails(app.database().ref("secret").once("value"));

assertSucceeds(pr: Promise) => Promise

Devuelve una promesa que tiene éxito si la entrada tiene éxito y se rechaza si se rechaza la entrada.

Utilice esto para afirmar que la lectura o escritura de una base de datos se realiza correctamente:

firebase.assertSucceeds(app.database().ref("public").once("value"));

Almacenamiento en la nube

initializeTestApp({ storageBucket: string, auth: Object }) => FirebaseApp

Úselo para crear una aplicación autenticada como un usuario específico para usar en las pruebas.

Devuelve una aplicación de Firebase inicializada correspondiente al nombre del depósito de almacenamiento y la anulación de la variable de autenticación especificada en las opciones.

firebase.initializeTestApp({
  storageBucket: "my-bucket",
  auth: { uid: "alice" }
});

initializeAdminApp({ storageBucket: string }) => FirebaseApp

Úselo para crear una aplicación autenticada como administrador para configurar el estado de las pruebas.

firebase.initializeAdminApp({ storageBucket: "my-bucket" });

loadStorageRules({ storageBucket: string, rules: Object }) => Promise

Úselo para establecer las reglas de su depósito de almacenamiento.

Envía reglas a depósitos de almacenamiento administrados localmente. Toma un objeto de opciones que especifica su "storageBucket" y sus "reglas" como cadenas.

firebase
      .loadStorageRules({
        storageBucket: "my-bucket",
        rules: fs.readFileSync("/path/to/storage.rules", "utf8")
      });

apps() => [FirebaseApp]

Devuelve todas las aplicaciones de prueba y administración actualmente inicializadas.

Use esto para limpiar aplicaciones entre o después de las pruebas (tenga en cuenta que las aplicaciones inicializadas con oyentes activos impiden que JavaScript salga):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Devuelve una promesa que se rechaza si la entrada se realiza correctamente y tiene éxito si se rechaza la entrada.

Utilice esto para afirmar que falla la lectura o escritura de un depósito de almacenamiento:

firebase.assertFails(app.storage().ref("letters/private.doc").getMetadata());

assertSucceeds(pr: Promise) => Promise

Devuelve una promesa que tiene éxito si la entrada tiene éxito y se rechaza si se rechaza la entrada.

Utilice esto para afirmar que la lectura o escritura de un depósito de almacenamiento se realizó correctamente:

firebase.assertFails(app.storage().ref("images/cat.png").getMetadata());