Uygulamanızı oluştururken, Cloud Firestore veritabanınıza erişimi kilitlemek isteyebilirsiniz. Ancak lansmandan önce daha incelikli Cloud Firestore Güvenlik Kurallarına ihtiyacınız olacak. Cloud Firestore öykünücüsü ile, uygulamanızın genel özelliklerini ve davranışını prototipleme ve test etmenin yanı sıra, Cloud Firestore Güvenlik Kurallarınızın davranışını kontrol eden birim testleri yazabilirsiniz.
Hızlı başlangıç
Basit kuralları olan 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ı kullandığınızda 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
match
bildirimi. - Bu belgelere erişimi kontrol eden bir
allow
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 veri okumadan veya yazmadan önce güvenlik kurallarınıza göre değerlendirilir. Kurallar, belirtilen belge yollarından herhangi birine erişimi reddederse, isteğin tamamı başarısız olur.
Cloud Firestore Güvenlik Kurallarını kullanmaya başlayın 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 kullanılı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ışır:
firebase emulators:start --only firestore
Çoğu durumda öykünücüyü başlatmak, bir test paketi çalıştırmak ve ardından 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"
Öykünücü başlatıldığında varsayılan bir bağlantı noktasında (8080) çalışmayı 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.json
dosyanızınfirestore.rules
alanında belirtilen kuralları yükleyecektir. 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ığı gibiloadFirestoreRules
yöntemini kullanmazsanız öykünücü, tüm projeleri açık kurallara sahipmiş gibi değerlendirir. - Çoğu Firebase SDK'sı öykünücülerle doğrudan çalışırken, yalnızca
@firebase/rules-unit-testing
kitaplığı Güvenlik Kurallarında sahteauth
doğrulamayı destekler ve birim testlerini çok daha kolaylaştırır. 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 entegrasyon ve manuel testlerde uygulamanızın doğrudan öykünücülere bağlanmasına olanak tanır.
Yerel birim testlerini ç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ı olan ve öykünücülere bağlanmak için daha az kurulum gerektiren v9 test kitaplığını öneriyoruz ve böylece üretim kaynaklarının yanlışlıkla kullanılmasını güvenli bir şekilde önlüyoruz. Geriye dönük uyumluluk için v8 test kitaplığını kullanıma sunmaya devam ediyoruz.
Yerel olarak çalışan emülatörle 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ı bir kez daha kontrol edin.
async/await
gösterimini kullanabilmeniz için Node.js'nin yeni bir sürümünü kullanmanızı kesinlikle öneririz. Test etmek isteyebileceğiniz davranışların neredeyse tamamı eşzamansız işlevler içerir ve test modülü Promise tabanlı kodla çalışacak şekilde tasarlanmıştır.
v9 Kuralları Birim Testi kitaplığı, öykünücülerden her zaman haberdardı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 birRulesTestEnvironment
oluşturma ve yapılandırma. - Test verilerini Kuralları tetiklemeden, onları geçici olarak atlamanıza izin veren bir kolaylık yöntemi kullanarak ayarlama,
RulesTestEnvironment.withSecurityRulesDisabled
. - Test verilerini ve ortamını temizlemek için,
RulesTestEnvironment.cleanup()
veyaRulesTestEnvironment.clearFirestore()
gibi çağrılarla test paketini ve test öncesi/sonrası kancalarını ayarlama. -
RulesTestEnvironment.authenticatedContext
veRulesTestEnvironment.unauthenticatedContext
kullanarak kimlik doğrulama durumlarını taklit eden test senaryolarını uygulama.
Yaygın yöntemler ve yardımcı işlevler
Ayrıca v9 SDK'daki öykünücüye özgü 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ışır durumda 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 eklenecektir. İ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 isteklerde Firebase Auth belirteçleri 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ı atlayarak bağlamı alan ve bir söz veren bir geri çağırma işlevi alır. Söz verildiğinde / reddedildiğinde bağlam yok edilecektir.
RulesTestEnvironment.cleanup()
Bu yöntem, test ortamında oluşturulan tüm RulesTestContexts
yok eder ve temeldeki kaynakları temizleyerek temiz bir çıkış sağlar.
Bu yöntem öykünücülerin durumunu hiçbir şekilde değiştirmez. Testler arasında verileri sıfırlamak için uygulamaya öykünücüye özel açık veri yöntemini kullanın.
assertSucceeds(pr: Promise<any>)) => Promise<any>
Bu bir test durumu yardımcı programı işlevidir.
İşlev, bir öykünücü işlemini sarmalayan sağlanan Taahhüdün Güvenlik Kuralları ihlali olmaksızın çözüleceğini iddia eder.
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });
assertFails(pr: Promise<any>)) => Promise<any>
Bu bir test durumu yardımcı programı işlevidir.
İşlev, bir emülatör işlemini sarmalayan sağlanan Taahhüdün bir Güvenlik Kuralları ihlaliyle reddedileceğini ileri sürer.
await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });
Öykünücüye özgü yöntemler
Ayrıca v9 SDK'daki yaygın 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ılmış 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 uyumlu) ile kullanılabilir.
Kural değerlendirmelerini görselleştirin
Cloud Firestore öykünücüsü, Firebase Güvenlik Kuralları için değerlendirme izleme dahil, istemci isteklerini Emulator Suite kullanıcı arayüzünde görselleştirmenize olanak tanır.
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ştur
Bir dizi testi çalıştırdıktan sonra, güvenlik kurallarınızdan 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 dahil olmak üzere daha fazla bilgi için fareyle üzerine getirebileceğiniz ifadelere ve alt ifadelere ayırır. 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
Öykünücü 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,
rules-unit-testing
kitaplığında birauth
alanı alaninitializeTestApp()
yöntemini sağladık. Bu yöntem kullanılarak oluşturulan Firebase tanıtıcısı, sağladığınız varlık olarak kimliği başarıyla doğrulanmış gibi davranacaktır.null
değerini iletirseniz, kimliği doğrulanmamış bir kullanıcı gibi davranır (örneğin,auth != null
kuralları 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 düzensiz davranışlarla ilgili sorunları gidermek için aşağıdaki yönergeleri izleyin. Bu notlar, Güvenlik Kuralları birim test kitaplığı dikkate alınarak yazılmıştır, ancak genel yaklaşımlar tüm Firebase SDK'ları için geçerlidir.
Test davranışı tutarsız
Testleriniz, testlerin kendilerinde herhangi bir değişiklik olmasa bile ara sıra başarılı ve başarısız oluyorsa, bunların düzgün bir şekilde sıralandığını doğrulamanız gerekebilir. Öykünücüyle çoğu etkileşim eşzamansızdır, bu nedenle tüm eşzamansız kodun düzgün bir şekilde sıralanıp sıralanmadığını bir kez daha kontrol edin. Sıralamayı, vaatleri zincirleyerek veya await
gösterimini özgürce kullanarak düzeltebilirsiniz.
Özellikle, aşağıdaki zaman uyumsuz işlemleri gözden geçirin:
- Örneğin, ile güvenlik kuralları ayarlamak,
initializeTestEnvironment
. - Örneğin,
db.collection("users").doc("alice").get()
ile veri okuma ve yazma. -
assertSucceeds
veassertFails
dahil olmak üzere işlemsel 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 kapatıldığında tüm veriler kaybolur. Aynı proje kimliğine karşı birden fazla 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 ayarlarken, verileri Cloud Firestore Güvenlik Kurallarınızın gerçekte izin vermediği bir ş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ı tetiklemez.
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 izin verdiğini/reddettiğini doğru bir şekilde doğrulamanıza olanak tanır.