Uygulamanızı oluştururken Cloud Firestore veritabanınıza erişimi kilitlemek isteyebilirsiniz. Ancak, başlatmadan önce daha ayrıntılı Cloud Firestore Güvenlik Kurallarına ihtiyacınız olacak. Cloud Firestore öykünücüsüyle, uygulamanızın genel özelliklerini ve davranışını prototiplemeye ve test etmeye ek olarak, Cloud Firestore Güvenlik Kurallarınızın davranışını kontrol eden birim testleri yazabilirsiniz.
Hızlı başlangıç
Basit kurallara sahip birkaç temel test senaryosu için hızlı başlangıç örneğini deneyin.
Cloud Firestore Güvenlik Kurallarını Anlayın
Mobil ve web istemci kitaplıklarını kullanırken sunucusuz kimlik doğrulama, yetkilendirme ve veri doğrulama için Firebase Kimlik Doğrulaması ve Cloud Firestore Güvenlik Kuralları uygulayın.
Cloud Firestore Güvenlik Kuralları iki parça içerir:
- Veritabanınızdaki belgeleri tanımlayan bir
matchifadesi. - Bu belgelere erişimi kontrol eden bir
allowver ifadesi.
Firebase Authentication, kullanıcıların kimlik bilgilerini doğrular ve kullanıcı tabanlı ve rol tabanlı erişim sistemleri için temel sağlar.
Bir Cloud Firestore mobil/web istemci kitaplığından gelen her veritabanı isteği, herhangi bir veriyi okumadan veya yazmadan önce güvenlik kurallarınıza göre değerlendirilir. Kurallar, belirtilen belge yollarından herhangi birine erişimi reddederse, tüm istek başarısız olur.
Cloud Firestore Güvenlik Kurallarını Kullanmaya Başlarken bölümünde Cloud Firestore Güvenlik Kuralları hakkında daha fazla bilgi edinin.
öykünücüyü yükleyin
Cloud Firestore öykünücüsünü yüklemek için Firebase CLI'yi kullanın ve aşağıdaki komutu çalıştırın:
firebase setup:emulators:firestore
öykünücüyü çalıştırın
Çalışma dizininizde bir Firebase projesi başlatarak başlayın. Bu, Firebase CLI'yi kullanırken yaygın olarak kullanılan bir ilk adımdır.
firebase init
Aşağıdaki komutu kullanarak öykünücüyü başlatın. Öykünücü, siz işlemi sonlandırana kadar çalışacaktır:
firebase emulators:start --only firestore
Çoğu durumda öykünücüyü başlatmak, bir test paketi çalıştırmak ve testler çalıştırıldıktan sonra öykünücüyü kapatmak istersiniz. Bunu emulators:exec komutunu kullanarak kolayca yapabilirsiniz:
firebase emulators:exec --only firestore "./my-test-script.sh"
Başlatıldığında, öykünücü varsayılan bir bağlantı noktasında (8080) çalıştırmayı dener. firebase.json dosyanızın "emulators" bölümünü değiştirerek öykünücü bağlantı noktasını değiştirebilirsiniz:
{
// ...
"emulators": {
"firestore": {
"port": "YOUR_PORT"
}
}
}
Öykünücüyü çalıştırmadan önce
Öykünücüyü kullanmaya başlamadan önce aşağıdakileri aklınızda bulundurun:
- Öykünücü, başlangıçta
firebase.jsondosyanızınfirestore.rulesalanında belirtilen kuralları yükler. Cloud Firestore Güvenlik Kurallarınızı içeren yerel bir dosyanın adını bekler ve bu kuralları tüm projelere uygular. Yerel dosya yolunu sağlamazsanız veya aşağıda açıklandığı gibiloadFirestoreRulesyöntemini kullanmazsanız, öykünücü tüm projeleri açık kurallara sahip olarak değerlendirir. - Çoğu Firebase SDK'sı doğrudan öykünücülerle çalışırken, yalnızca
@firebase/rules-unit-testingkitaplığı Güvenlik Kurallarında alaycıauthdestekleyerek birim testlerini çok daha kolay hale getirir. Ayrıca kitaplık, aşağıda listelendiği gibi tüm verileri temizleme gibi öykünücüye özgü birkaç özelliği destekler. - Öykünücüler ayrıca İstemci SDK'ları aracılığıyla sağlanan üretim Firebase Auth belirteçlerini kabul edecek ve kuralları buna göre değerlendirecek, bu da uygulamanızı entegrasyon ve manuel testlerde doğrudan öykünücülere bağlamanıza olanak tanır.
Yerel birim testleri çalıştırın
v9 JavaScript SDK ile yerel birim testleri çalıştırın
Firebase, hem sürüm 9 JavaScript SDK'sı hem de sürüm 8 SDK'sı ile bir Güvenlik Kuralları birim test kitaplığı dağıtır. Kitaplık API'leri önemli ölçüde farklıdır. Daha akıcı ve öykünücülere bağlanmak için daha az kurulum gerektiren ve böylece üretim kaynaklarının kazara kullanılmasını güvenli bir şekilde önleyen v9 test kitaplığını öneriyoruz. Geriye dönük uyumluluk için v8 test kitaplığını kullanıma sunmaya devam ediyoruz.
- v9 SDK'daki ortak test yöntemleri ve yardımcı program işlevleri
- v9 SDK'da öykünücüye özel test yöntemleri
Yerel olarak çalışan öykünücüyle etkileşim kurmak için @firebase/rules-unit-testing modülünü kullanın. Zaman aşımları veya ECONNREFUSED hataları alırsanız, öykünücünün gerçekten çalışıp çalışmadığını iki kez kontrol edin.
async/await gösterimini kullanabilmeniz için Node.js'nin en son sürümünü kullanmanızı şiddetle öneririz. Test etmek isteyebileceğiniz davranışların neredeyse tamamı eşzamansız işlevleri içerir ve test modülü Promise tabanlı kodla çalışmak üzere tasarlanmıştır.
v9 Kuralları Birimi Test kitaplığı, öykünücülerin her zaman farkındadır ve üretim kaynaklarınıza asla dokunmaz.
Kitaplığı v9 modüler içe aktarma deyimlerini kullanarak içe aktarırsınız. Örneğin:
import {
assertFails,
assertSucceeds,
initializeTestEnvironment,
RulesTestEnvironment,
} 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ıldıktan sonra, birim testlerinin uygulanması şunları içerir:
-
initializeTestEnvironmentçağrısıyla birRulesTestEnvironmentoluşturma ve yapılandırma. - Kuralları tetiklemeden test verilerini ayarlama, onları geçici olarak atlamanıza izin veren bir kolaylık yöntemi kullanarak,
RulesTestEnvironment.withSecurityRulesDisabled. -
RulesTestEnvironment.cleanup()veyaRulesTestEnvironment.clearFirestore()gibi test verilerini ve ortamını temizlemek için çağrılarla kancalardan önce/sonra test paketi ve test başına test ayarlama. -
RulesTestEnvironment.authenticatedContextveRulesTestEnvironment.unauthenticatedContextkullanarak kimlik doğrulama durumlarını taklit eden test senaryolarının uygulanması.
Ortak yöntemler ve yardımcı işlevler
Ayrıca v9 SDK'daki öykünücüye özel test yöntemlerine bakın .
initializeTestEnvironment() => RulesTestEnvironment
Bu işlev, kural birimi testi için bir test ortamı başlatır. Test kurulumu için önce bu işlevi çağırın. Başarılı yürütme, öykünücülerin çalışıyor olmasını gerektirir.
İşlev, bir proje kimliği ve öykünücü yapılandırma ayarlarından oluşabilen bir TestEnvironmentConfig tanımlayan isteğe bağlı bir nesneyi kabul eder.
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 Kimlik Doğrulama kullanıcısı gibi davranan bir RulesTestContext oluşturur. Döndürülen bağlam aracılığıyla oluşturulan isteklere sahte bir Kimlik Doğrulama belirteci eklenir. İsteğe bağlı olarak, Kimlik Doğrulama belirteci yükleri için özel talepleri veya geçersiz kılmaları tanımlayan bir nesne iletin.
initializeTestEnvironment ile yapılandırılanlar da dahil olmak üzere yapılandırılmış tüm öykünücü ö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 aracılığıyla oturum açmamış bir istemci gibi davranan bir RulesTestContext oluşturur. Döndürülen bağlam aracılığıyla oluşturulan isteklere Firebase Auth jetonları eklenmez.
initializeTestEnvironment ile yapılandırılanlar da dahil olmak üzere yapılandırılmış tüm öykünücü ö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 bir test kurulumu işlevi çalıştırın.
Bu yöntem, Güvenlik Kurallarını atlama bağlamını alan ve bir söz veren bir geri arama işlevi alır. Söz çözüldüğünde/reddedildiğinde bağlam yok edilecektir.
RulesTestEnvironment.cleanup()
Bu yöntem, test ortamında oluşturulan tüm RulesTestContexts yok eder ve temel kaynakları temizleyerek temiz bir çıkışa izin verir.
Bu yöntem emülatörlerin durumunu hiçbir şekilde değiştirmez. Testler arasında verileri sıfırlamak için uygulama öykünücüsüne özel net veri yöntemini kullanın.
assertSucceeds(pr: Promise<any>)) => Promise<any>
Bu bir test senaryosu yardımcı program işlevidir.
İşlev, bir öykünücü işlemi saran sağlanan Söz'ün Güvenlik Kuralları ihlali olmadan çözüleceğini iddia eder.
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });
assertFails(pr: Promise<any>)) => Promise<any>
Bu bir test senaryosu yardımcı program işlevidir.
İşlev, bir öykünme işlemini saran sağlanan Söz'ün Güvenlik Kuralları ihlaliyle reddedileceğini iddia eder.
await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });
Öykünücüye özgü yöntemler
Ayrıca v9 SDK'daki genel test yöntemlerine ve yardımcı program işlevlerine bakın .
RulesTestEnvironment.clearFirestore() => Promise<void>
Bu yöntem, Firestore öykünücüsü için yapılandırılan proje projectId ait olan 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 Client SDK örneği, istemci SDK API'leri (v9 modüler veya v9 uyumluluğu) ile kullanılabilir.
Kural değerlendirmelerini görselleştirin
Cloud Firestore öykünücüsü, Firebase Güvenlik Kuralları için değerlendirme izleme de dahil olmak üzere, Emulator Suite Kullanıcı Arabiriminde istemci isteklerini görselleştirmenize olanak tanır.
Her istek için ayrıntılı değerlendirme sırasını görüntülemek için Firestore > İstekler sekmesini açın.
Test raporları oluşturun
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, öykünücü çalışırken açıkta kalan 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, kurallarınızı, değerlendirme sayısı ve döndürülen değerler de dahil olmak üzere daha fazla bilgi için fareyle üzerine gelebileceğiniz ifadelere ve alt ifadelere böler. 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 ve üretim arasındaki farklar
- Açıkça bir Cloud Firestore projesi oluşturmanız gerekmez. Öykünücü, erişilen herhangi bir örneği otomatik olarak oluşturur.
- Cloud Firestore öykünücüsü, normal Firebase Kimlik Doğrulama akışıyla çalışmaz. Bunun yerine, Firebase Test SDK'sında, bir
authalanı alanrules-unit-testingkitaplığındainitializeTestApp()yöntemini sağladık. Bu yöntem kullanılarak oluşturulan Firebase tanıtıcısı, sağladığınız varlık olarak başarıyla doğrulanmış gibi davranacaktır.nulldeğerini iletirseniz, kimliği doğrulanmamış bir kullanıcı gibi davranır (örneğin,auth != nullkuralları başarısız olur).
Bilinen sorunları giderme
Cloud Firestore öykünücüsünü kullanırken aşağıdaki bilinen sorunlarla karşılaşabilirsiniz. Karşılaştığınız herhangi bir düzensiz davranışı gidermek için aşağıdaki yönergeleri izleyin. Bu notlar Güvenlik Kuralları birim test kitaplığı göz önünde bulundurularak yazılmıştır, ancak genel yaklaşımlar tüm Firebase SDK'ları için geçerlidir.
Test davranışı tutarsız
Testleriniz ara sıra geçiyor ve başarısız oluyorsa, testlerin kendisinde herhangi bir değişiklik olmasa bile, bunların düzgün bir şekilde sıralandığını doğrulamanız gerekebilir. Öykünücüyle olan etkileşimlerin çoğu eşzamansızdır, bu nedenle tüm eşzamansız kodun düzgün şekilde sıralandığını iki kez kontrol edin. Sıralamayı, vaatleri zincirleyerek veya await notasyonunu özgürce kullanarak düzeltebilirsiniz.
Özellikle, aşağıdaki zaman uyumsuz işlemleri gözden geçirin:
- Örneğin,
initializeTestEnvironmentile güvenlik kurallarını ayarlama. - Örneğin,
db.collection("users").doc("alice").get()ile veri okuma ve yazma. -
assertSucceedsveassertFailsdahil olmak üzere operasyonel iddialar.
Testler yalnızca öykünücüyü ilk yüklediğinizde geçer
Öykünücü durum bilgilidir. Kendisine yazılan tüm verileri bellekte saklar, böylece öykünücü her kapandığında tüm veriler kaybolur. Aynı proje kimliğine karşı birden çok test çalıştırıyorsanız, her test sonraki testleri etkileyebilecek veriler üretebilir. Bu davranışı atlamak için aşağıdaki yöntemlerden herhangi 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 gerekeceğini unutmayın; kurallar yalnızca varsayılan proje kimliği için otomatik olarak yüklenir. - Testlerinizi önceden yazılmış verilerle etkileşime girmeyecek şekilde yeniden yapılandırın (örneğin, her test için farklı bir koleksiyon kullanın).
- Test sırasında yazılan tüm verileri silin.
Test kurulumu çok karmaşık
Testinizi kurarken, verileri Cloud Firestore Güvenlik Kurallarınızın gerçekten izin vermediği şekilde değiştirmek isteyebilirsiniz. Kurallarınız test kurulumunu karmaşık hale getiriyorsa, kurulum adımlarınızda RulesTestEnvironment.withSecurityRulesDisabled kullanmayı deneyin, böylece okuma ve yazma işlemleri PERMISSION_DENIED hatalarını tetiklemeyecektir.
Bundan sonra testiniz, sırasıyla RulesTestEnvironment.authenticatedContext ve unauthenticatedContext kullanarak kimliği doğrulanmış veya kimliği doğrulanmamış bir kullanıcı olarak işlemler gerçekleştirebilir. Bu, Cloud Firestore Güvenlik Kurallarınızın farklı durumlara doğru şekilde izin verdiğini/reddettiğini doğrulamanıza olanak tanır.