Uygulamanızı oluştururken Cloud Firestore veritabanınıza erişimi kilitlemek isteyebilirsiniz. Ancak lansmandan önce daha ayrıntılı bir analize ihtiyacınız vardırCloud Firestore Security Rules. Cloud Firestore emülatörüyle, uygulamanızın genel özelliklerini ve davranışını prototip haline getirmenin ve test etmenin yanı sıra Cloud Firestore Security Rules'ınızın davranışını kontrol eden birim testleri de yazabilirsiniz.
Hızlı başlangıç kılavuzu
Basit kurallar içeren birkaç temel test durumu için hızlı başlangıç örneğini deneyin.
Cloud Firestore Security Rules hakkında bilgi edinme
Mobil ve web istemci kitaplıklarını kullanırken sunucusuz kimlik doğrulama, yetkilendirme ve veri doğrulama için Firebase Authentication ve Cloud Firestore Security Rules uygulamalarını uygulayın.
Cloud Firestore Security Rules iki parçadan oluşur:
- Veritabanınıza ait dokümanları tanımlayan bir
matchifadesi. - Bu dokümanlara erişimi kontrol eden bir
allowifadesi.
Firebase Authentication, kullanıcıların kimlik bilgilerini doğrular ve kullanıcıya dayalı ve role dayalı erişim sistemlerinin temelini oluşturur.
Cloud Firestore mobil/web istemci kitaplığından gelen her veritabanı isteği, herhangi bir veri okumadan veya yazmadan önce güvenlik kurallarınıza göre değerlendirilir. Kurallar, belirtilen doküman yollarından herhangi birine erişimi reddederse isteğin tamamı başarısız olur.
Cloud Firestore Security Rules'ü kullanmaya başlama başlıklı makalede Cloud Firestore Security Rules hakkında daha fazla bilgi edinin.
Emülatörü yükleme
Cloud Firestore emülatörünü yüklemek için Firebase KSA'yı kullanın ve aşağıdaki komutu çalıştırın:
firebase setup:emulators:firestore
Emülatörü çalıştırma
Çalışma dizininizde bir Firebase projesini başlatarak başlayın. Bu, Firebase CLI'yi kullanırken uygulanan yaygın bir ilk adımdır.
firebase init
Aşağıdaki komutu kullanarak emülatörü başlatın. Emülatör siz işlemi sonlandırana kadar çalışır.
firebase emulators:start --only firestore
Çoğu durumda, emülatör başlatmak, bir test paketi çalıştırmak ve ardından testler çalıştıktan sonra emülatörü kapatmak istersiniz. Bu işlemi emulators:exec komutunu kullanarak kolayca yapabilirsiniz:
firebase emulators:exec --only firestore "./my-test-script.sh"
Emülatör, başlatıldığında varsayılan bağlantı noktasında (8080) çalışmaya çalışır. firebase.json dosyanızın "emulators" bölümünü değiştirerek emülatör bağlantı noktasını değiştirebilirsiniz:
{
// ...
"emulators": {
"firestore": {
"port": "YOUR_PORT"
}
}
}Emülatörü çalıştırmadan önce
Emülatörü kullanmaya başlamadan önce aşağıdakileri göz önünde bulundurun:
- Emülatör başlangıçta
firebase.jsondosyanızıfirestore.rulesalanında belirtilen kuralları yükler. Cloud Firestore Security Rules dosyanızı içeren yerel bir dosyanın adını bekler ve bu kuralları tüm projelere uygular. Yerel dosya yolunu belirtmez veya aşağıda açıklandığı gibiloadFirestoreRulesyöntemini kullanmazsanız emülatör tüm projeleri açık kurallara sahip olarak değerlendirir. - Çoğu Firebase SDK'sı doğrudan emülatörlerle çalışırken yalnızca
@firebase/rules-unit-testingkitaplığı, Security Rules'daauthtaklit etmeyi destekler. Bu da birim testlerini çok daha kolay hale getirir. Ayrıca kitaplık, aşağıda listelenen tüm verileri temizleme gibi emülatöre özgü birkaç özelliği destekler. - Emülatörler ayrıca istemci SDK'ları aracılığıyla sağlanan üretim Firebase Auth jetonlarını da kabul edecek ve kuralları uygun şekilde değerlendirecektir. Böylece uygulamanız, entegrasyon ve manuel testlerde doğrudan emülatörlere bağlanabilecektir.
Yerel birim testleri çalıştırma
v9 JavaScript SDK'sı ile yerel birim testleri çalıştırma
Firebase, hem 9 numaralı JavaScript SDK'sı hem de 8 numaralı SDK'sıyla birlikte bir Güvenlik Kuralları birim testi kitaplığı dağıtır. Kitaplık API'leri önemli ölçüde farklıdır. Daha basit ve emülatörlere bağlanmak için daha az kurulum gerektiren v9 test kitaplığını öneririz. Böylece, üretim kaynaklarının yanlışlıkla kullanılmasını güvenli bir şekilde önleyebilirsiniz. Geriye dönük uyumluluk için v8 test kitaplığını kullanıma sunmaya devam ediyoruz.
- v9 SDK'sında yaygın test yöntemleri ve yardımcı program işlevleri
- v9 SDK'sındaki emülatöre özgü test yöntemleri
Yerel olarak çalışan emülatörle etkileşimde bulunmak için @firebase/rules-unit-testing modülünü kullanın. Zaman aşımı veya ECONNREFUSED hataları alırsanız emülatörünün gerçekten çalıştığından emin olun.
async/await gösterimini kullanabilmek için Node.js'nin güncel bir sürümünü kullanmanızı önemle tavsiye ederiz. Test etmek isteyebileceğiniz davranışların neredeyse tamamı eşzamansız işlevleri kapsar ve test modülü, Promise tabanlı kodla çalışacak şekilde tasarlanmıştır.
v9 Kurallar Birim Testi kitaplığı, her zaman emülatörlerden haberdardır ve üretim kaynaklarınıza hiçbir zaman dokunmaz.
Kitaplığı, v9 modüler içe aktarma ifadelerini kullanarak içe aktarırsınız. Örneğin:
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.
İçe aktarılan birim testlerini uygulamak için:
initializeTestEnvironment'a çağrı göndererekRulesTestEnvironmentoluşturma ve yapılandırma.- Kuralları tetiklemeden test verileri oluşturma. Bu işlemi, kuralları geçici olarak atlamanıza olanak tanıyan bir kolaylık yöntemi kullanarak yapabilirsiniz.
RulesTestEnvironment.withSecurityRulesDisabled - Test verileriyle ortamı temizlemek için
RulesTestEnvironment.cleanup()veyaRulesTestEnvironment.clearFirestore()gibi çağrılar içeren test grubu ve test başına önce/sonra kancaları ayarlama. RulesTestEnvironment.authenticatedContextveRulesTestEnvironment.unauthenticatedContextkullanarak kimlik doğrulama durumlarını taklit eden test durumları uygulama
Yaygın yöntemler ve yardımcı işlevler
v9 SDK'sındaki emülatöre özgü test yöntemlerine de bakın.
initializeTestEnvironment() => RulesTestEnvironment
Bu işlev, kural birim testi için bir test ortamı oluşturur. Test kurulumu için önce bu işlevi çağırın. Başarılı bir yürütme için emülatörlerin çalışıyor olması gerekir.
İşlev, bir TestEnvironmentConfig tanımlayan isteğe bağlı bir nesneyi kabul eder. Bu nesne, proje kimliği ve emülatör yapılandırma ayarlarından oluşabilir.
let testEnv = await initializeTestEnvironment({ projectId: "demo-project-1234", firestore: { rules: fs.readFileSync("firestore.rules", "utf8"), }, });
RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext
Bu yöntem, kimliği doğrulanmış bir kullanıcı gibi davranan bir RulesTestContext oluşturur. Döndürülen bağlam üzerinden oluşturulan isteklere sahte bir kimlik doğrulama jetonu eklenir. İsteğe bağlı olarak, Kimlik doğrulama jetonu yükleri için özel talepler veya geçersiz kılmalar tanımlayan bir nesne iletin.
initializeTestEnvironment ile yapılandırılanlar da dahil olmak üzere yapılandırılmış herhangi bir emülatör örneklerine erişmek için testlerinizde döndürülen test bağlam nesnesini kullanın.
// 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
Bu yöntem, kimlik doğrulama üzerinden giriş yapmayan bir istemci gibi davranan bir RulesTestContext oluşturur. Döndürülen bağlam aracılığıyla oluşturulan isteklerde Firebase Auth jetonları eklenmez.
initializeTestEnvironment ile yapılandırılanlar da dahil olmak üzere yapılandırılmış tüm emülatör örneklerine erişmek için testlerinizde döndürülen test bağlamı nesnesini kullanın.
// 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()
Güvenlik Kuralları devre dışı bırakılmış gibi davranan bir bağlamla test kurulumu işlevi çalıştırın.
Bu yöntem, Güvenlik Kurallarını Atlama bağlamını alan ve bir promise döndüren bir geri çağırma işlevi alır. Sözleşme çözüldükten veya reddedildikten sonra bağlam yok edilir.
RulesTestEnvironment.cleanup()
Bu yöntem, test ortamında oluşturulan tüm RulesTestContexts öğelerini yok eder ve temel kaynakları temizleyerek temiz bir çıkış sağlar.
Bu yöntem, emülatörlerin durumunu hiçbir şekilde değiştirmez. Testler arasında verileri sıfırlamak için uygulama emülatörüne özel veri temizleme yöntemini kullanın.
assertSucceeds(pr: Promise<any>)) => Promise<any>
Bu, test amaçlı bir yardımcı program işlevidir.
İşlev, bir emülatör işlemini sarmalayan sağlanan Promise'in Güvenlik Kuralları ihlali olmadan çözüleceğini belirtir.
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });assertFails(pr: Promise<any>)) => Promise<any>
Bu, test amaçlı bir yardımcı program işlevidir.
İşlev, bir emülatör işlemini sarmalayan sağlanan Promise'in güvenlik kuralları ihlali nedeniyle reddedileceğini belirtir.
await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });Emülatöre özel yöntemler
v9 SDK'sındaki yaygın test yöntemleri ve yardımcı işlevler konusuna da bakın.
RulesTestEnvironment.clearFirestore() => Promise<void>
Bu yöntem, Firestore emülatörü için yapılandırılmış projectId'ye ait Firestore veritabanındaki verileri temizler.
RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;
Bu yöntem, bu test bağlamı için bir Firestore örneği alır. Döndürülen Firebase JS istemci SDK'sı örneği, istemci SDK API'leriyle (modüler v9 veya uyumlu v9) kullanılabilir.
Kural değerlendirmelerini görselleştirme
Cloud Firestore emülatörü, Firebase Güvenlik Kuralları için değerlendirme izleme dahil olmak üzere, istemci isteklerini Emulator Suite kullanıcı arayüzünde görselleştirmenizi sağlar.
Her istek için ayrıntılı değerlendirme sırasını görüntülemek üzere Firestore > İstekler sekmesini açın.
Test raporları oluşturma
Bir dizi test çalıştırdıktan sonra, güvenlik kurallarınızın her birinin nasıl değerlendirildiğini gösteren test kapsamı raporlarına erişebilirsiniz.
Raporları almak için emülatör çalışırken açığa çıkan bir uç noktayı sorgulayın. Tarayıcı dostu bir sürüm için aşağıdaki URL'yi kullanın:
http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage.html
Bu işlem, kurallarınızı ifade ve alt ifadelere ayırır. Fareyle üzerine geldiğinizde değerlendirmelerin sayısı ve döndürülen değerler gibi daha fazla bilgi edinebilirsiniz. Bu verilerin ham JSON sürümü için sorgunuza aşağıdaki URL'yi ekleyin:
http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage
Emülatör ile üretim arasındaki farklar
- Cloud Firestore projesini açıkça oluşturmanız gerekmez. Emülatör, erişilen her örneği otomatik olarak oluşturur.
- Cloud Firestore emülatörü, normal Firebase Authentication akışıyla çalışmaz.
Bunun yerine Firebase Test SDK'sında,
rules-unit-testingkitaplığındaauthalanı alaninitializeTestApp()yöntemini sağladık. Bu yöntem kullanılarak oluşturulan Firebase herkese açık kullanıcı adı, sağladığınız varlık kimliği başarıyla doğrulanmış gibi davranır.nullöğesini iletirseniz kimliği doğrulanmamış kullanıcı olarak davranır (örneğin,auth != nullkuralları başarısız olur).
Bilinen sorunları giderme
Cloud Firestore emülatörünü kullanırken aşağıdaki bilinen sorunlarla karşılaşabilirsiniz. Karşılaştığınız anormal davranışları gidermek için aşağıdaki talimatları uygulayın. Bu notlar, Güvenlik Kuralları birimi test kitaplığı göz önünde bulundurularak yazılmış olsa da genel yaklaşımlar tüm Firebase SDK'ları için geçerlidir.
Test davranışı tutarlı değil
Testlerinizde herhangi bir değişiklik yapılmamasına rağmen zaman zaman başarılı ve başarısız sonuçlar alıyorsanız testlerin doğru şekilde sıralandığını doğrulamanız gerekebilir.
Emülatörle yapılan etkileşimlerin çoğu eşzamansız olduğundan, tüm eşzamansız kodun doğru şekilde sıralandığından emin olun. Sırayı, await gösterimini bolca kullanarak veya vaatleri zincirleyerek düzeltebilirsiniz.
Özellikle aşağıdaki asenkron işlemleri inceleyin:
- Örneğin
initializeTestEnvironmentile güvenlik kuralları ayarlama. - Veri okuma ve yazma (örneğin,
db.collection("users").doc("alice").get()). assertSucceedsveassertFailsdahil olmak üzere operasyonel iddialar.
Testler yalnızca emülatörü ilk kez yüklediğinizde geçer.
Emülatör durum bilgili. Kendisine yazılan tüm verileri bellekte depolar. Böylece emülatör her kapatıldığında tüm veriler kaybolur. Aynı proje kimliğiyle birden fazla test çalıştırırsanız her test, sonraki testleri etkileyebilecek veriler üretebilir. Bu davranışı atlamak için aşağıdaki yöntemlerden birini kullanabilirsiniz:
- Her test için benzersiz proje kimlikleri kullanın. Bunu yapmayı seçerseniz her testin bir parçası olarak
initializeTestEnvironment'ü çağırmanız gerektiğini unutmayın. Kurallar yalnızca varsayılan proje kimliği için otomatik olarak yüklenir. - Testlerinizi, daha önce yazılmış verilerle etkileşime girmeyecek şekilde yeniden yapılandırın (örneğin, her test için farklı bir koleksiyon kullanın).
- Bir test sırasında yazılan tüm verileri silin.
Test kurulumu çok karmaşık
Testinizi oluştururken verileri Cloud Firestore Security Rules'ün aslında izin vermediği bir şekilde değiştirmek isteyebilirsiniz. Kurallarınız test kurulumunu karmaşık hale getiriyorsa okuma ve yazma işlemlerinin PERMISSION_DENIED hatalarını tetiklememesi için kurulum adımlarınızda RulesTestEnvironment.withSecurityRulesDisabled kullanmayı deneyin.
Ardından, testiniz sırasıyla RulesTestEnvironment.authenticatedContext ve unauthenticatedContext kullanarak kimliği doğrulanmış veya doğrulanmamış bir kullanıcı olarak işlem gerçekleştirebilir. Bu sayede, Cloud Firestore Security Rules'ün farklı durumları doğru şekilde izin verdiğini/reddettiğini doğrulayabilirsiniz.