開源 | Canyon:提升JavaScript代碼質(zhì)量的全面覆蓋率分析工具
作者簡介
wr_zhang25,攜程資深前端開發(fā)工程師,關(guān)注前端代碼覆蓋率、JavaScript開源方向。
Liang, 攜程資深研發(fā)經(jīng)理,質(zhì)量專家,專注質(zhì)量工程領(lǐng)域。
一、背景
istanbuljs 是一款優(yōu)秀的JavaScript代碼覆蓋率工具,主要用于單元測試的代碼覆蓋率檢測和生成本地覆蓋率報告。然而,隨著現(xiàn)代前端技術(shù)和UI自動化測試的發(fā)展,對端到端測試的代碼覆蓋率檢測需求逐漸增加,istanbuljs提供的功能顯得捉襟見肘。
在攜程內(nèi)部JavaScript代碼覆蓋率使用的是gitlab內(nèi)置的coverage上報,也是只支持單元測試的覆蓋率收集和概覽數(shù)據(jù)展示。隨著攜程的前端技術(shù)日益精進(jìn),我們有了自己的前端流量錄制平臺,并且部署了相當(dāng)大規(guī)模的模擬器集群進(jìn)行UI自動化(flybirds)回放。這種場景下,需要對端到端測試的代碼覆蓋率進(jìn)行收集和展示,以便開發(fā)同學(xué)更好的了解到自己的代碼質(zhì)量。
傳統(tǒng)的istanbuljs提供的功能已經(jīng)無法滿足我們的需求。我們需要處理UI自動化過程中來自前端高并發(fā)的覆蓋率上報,實時的覆蓋率聚合,以及覆蓋率數(shù)據(jù)的聚合展示。因此,我們在Istanbuljs的基礎(chǔ)上開發(fā)了Canyon,解決端到端測試覆蓋率難收集的問題。
目前,攜程的多個部門已經(jīng)開始使用Canyon,并在持續(xù)集成流水線構(gòu)建階段插入探針代碼,在UI自動化測試階段收集和上報覆蓋率數(shù)據(jù)。服務(wù)端實時生成詳盡的覆蓋率報告,為UI自動化測試用例提供全面的覆蓋率數(shù)據(jù)指標(biāo)。
二、介紹
Canyon 通過簡單的 Babel 插件配置即可實現(xiàn)代碼插裝、覆蓋率上報和實時報告生成。其技術(shù)棧完全基于 JavaScript,只需 Node.js 環(huán)境即可運行,部署方便,適用于云原生環(huán)境的部署(如 Docker、Kubernetes)。
應(yīng)用的架構(gòu)設(shè)計適用于處理高頻、大規(guī)模的覆蓋率數(shù)據(jù)上報,能夠應(yīng)對 UI 自動化測試中的各種場景。同時,Canyon 與現(xiàn)有的 CI/CD 工具(如 GitLab CI、Jenkins)無縫集成,使用戶能夠輕松地在持續(xù)集成流水線中使用。
架構(gòu)圖如下:
下面會根據(jù)以下幾個部分來介紹 Canyon 的主要功能:
- 代碼覆蓋率
- 代碼插樁
- 測試與上報
- 覆蓋率聚合
- 覆蓋率報告
- 變更代碼覆蓋率
- react native 覆蓋率收集方案
- 覆蓋率提升優(yōu)先級列表
三、代碼覆蓋率
隨著編寫更多的end-to-end測試case,你會發(fā)現(xiàn)有一些疑問,我需要寫更多的測試用例嗎?究竟還有哪些代碼沒測到?用例會不會重復(fù)了?這個時候代碼覆蓋率就派上用場了,它的原理是在代碼執(zhí)行前將代碼探針插入到源代碼中(其實就是上下文加計數(shù)器),這樣每當(dāng)case執(zhí)行的時候就可以觸發(fā)其中的計數(shù)器。
在代碼中插入代碼探針的步驟稱為代碼插樁(instrument)。插樁前的代碼:
// add.js
function add(a, b) {
return a + b
}
module.exports = { add }
插樁過程是對代碼解析以查找所有函數(shù)、語句和分支,然后將計數(shù)器插入代碼中。對于上面的代碼,插樁完成后:
// 這個對象用于計算每個函數(shù)和每個語句被執(zhí)行的次數(shù)
const c = (window.__coverage__ = {
// "f" 記錄每個函數(shù)被調(diào)用的次數(shù)
f: [0],
// "s" 記錄每個語句被調(diào)用的次數(shù)
// 我們有3個語句,它們都從0開始
s: [0, 0, 0],
})
// 第一個語句定義了函數(shù)
c.s[0]++
function add(a, b) {
// 函數(shù)被調(diào)用后是第二個語句
c.f[0]++
c.s[1]++
return a + b
}
// 第三個語句即將被調(diào)用
c.s[2]++
module.exports = { add }
我們希望確保文件中的每個語句和函數(shù)add.js都已被我們的測試至少執(zhí)行一次。因此我們編寫一個測試:
// add.cy.js
const { add } = require('./add')
it('adds numbers', () => {
expect(add(2, 3)).to.equal(5)
})
當(dāng)測試調(diào)用時add(2, 3),執(zhí)行“add”函數(shù)內(nèi)的計數(shù)器遞增,覆蓋范圍對象變?yōu)椋?/span>
{
f: [1],
s: [1, 1, 1]
}
這個測試用例覆蓋率達(dá)到了100%,每個函數(shù)和每個語句都至少執(zhí)行了一次。但是在實際應(yīng)用中,要達(dá)到100%的代碼覆蓋率需要多次測試。
這是覆蓋率的基本介紹,有了這個前置知識,方便大家理解下面的內(nèi)容。
四、代碼插樁(instrumenting-code)
代碼覆蓋率最重要的一環(huán)就是代碼插樁
istanbuljs 是久經(jīng)沙場的js代碼插樁黃金標(biāo)準(zhǔn)。Canyon主要為端到端測試提供解決方案,經(jīng)過大量的實驗驗證,現(xiàn)代化前端工程的覆蓋率插樁必須要編譯時插樁。具體原因是istanbuljs提供的nyc插樁工具只能對原生js進(jìn)行插樁,然而前端模版語法層出不窮,例如ts、tsx、vue,雖然nyc也可以插樁,但是結(jié)構(gòu)實踐證明直接插樁的覆蓋率效果不盡人意,無法精確到該插樁到的函數(shù)、語句、分支。
幸運的是經(jīng)過調(diào)研,我們發(fā)現(xiàn)了babel-plugin-istanbul、vite-plugin-istanbul(experimental)、swc-plugin-coverage-instrument(experimental)。等類型工程的插樁解決方案。這些方案無一例外都是在前端工程編譯階段在將代碼分析成ast抽象語法樹的時候在適當(dāng)時機(jī)進(jìn)行插樁方法調(diào)用,更精確的插樁到的函數(shù)、語句、分支。
適用的工程類型:
工程類型 | 方案 |
vanilla javascript | nyc |
babel | babel-plugin-istanbul |
vite | vite-plugin-istanbul (experimental) |
swc | swc-plugin-coverage-instrument (experimental) |
用戶可以根據(jù)自己的工程類型選擇合適的插樁方案,只需要在工程中安裝對應(yīng)的插件,然后就會在編譯時自動插樁。
以babel.config.js為例:
module.exports = {
plugins: [
[
'babel-plugin-istanbul',
{
exclude: ['**/*.spec.js', '**/*.spec.ts', '**/*.spec.tsx', '**/*.spec.jsx'],
},
],
],
};
插樁完成后,代碼中會插入一些代碼探針,這些代碼探針會在運行時收集覆蓋率數(shù)據(jù),然后上報到Canyon服務(wù)端。
檢查是否插樁成功,可以在編譯后的產(chǎn)物中搜索__coverage__,如果有則說明插樁成功。
為了緊密關(guān)聯(lián)插樁代碼的源代碼,我們適配了各種provider,將環(huán)境變量發(fā)送到Canyon服務(wù)端,兌換到reportID,方便覆蓋率數(shù)據(jù)聚合計算完成后的覆蓋率源文件的關(guān)聯(lián)展示。
我們還提供了babel-plugin-canyon的babel插件,可以在各種流水線內(nèi)(aws,gitlab ci)讀取環(huán)境變量(branch、sha),以供后續(xù)覆蓋率數(shù)據(jù)與對應(yīng)的gitlab源代碼關(guān)聯(lián)。
babel.config.js
module.exports = {
plugins: [
[
'babel-plugin-canyon',
{
provider: 'gitlab',
branch: process.env.CI_COMMIT_REF_NAME,
sha: process.env.CI_COMMIT_SHA,
},
],
],
};
支持的提供商:
- Azure Pipelines
- CircleCI
- Drone
- Github Actions
- GitLab CI
- Jenkins
- Travis CI
需要特別注意的是,代碼探針的插樁會在構(gòu)建產(chǎn)物上下文加上代碼探針,會是代碼整體產(chǎn)物增大30%,建議不要上生產(chǎn)環(huán)境。
五、測試與上報
當(dāng)插樁完成發(fā)布到測試環(huán)境后,我們就可以進(jìn)行測試了。拿playwright舉例,對于插樁成功的前端應(yīng)用站點,window對象上面都會掛載__coverage__和__canyon__對象,我們需要在playwright測試過程中收集并上報這些數(shù)據(jù)到canyon的服務(wù)端。
playwright示例:
const {chromium} = require('playwright');
const main = async () => {
const browser = await chromium.launch()
const page = await browser.newPage();
// 進(jìn)入被測頁面
await page.goto('http://test.com')
// 執(zhí)行測試用例
// 用例1
await page.click('button')
// 用例2
await page.fill('input', 'test')
// 用例3
await page.click('text=submit')
const coverage = await page.evaluate(`window.__coverage__`)
// 收集上報覆蓋率
upload(coverage)
browser.close()
}
main()
攜程內(nèi)部有自己的UI自動化平臺 flybirds,我們在flybirds內(nèi)部集成了Canyon覆蓋率數(shù)據(jù)的收集和上報。真實的瀏覽器UI自動化測試的覆蓋率收集場景較為復(fù)雜,主要體現(xiàn)在多頁面(MPA)的覆蓋率收集時機(jī)不確定性。
單頁面(SPA)與多頁面(MPA)
當(dāng)測試用例執(zhí)行完成后,對于單頁面應(yīng)用(SPA)或者多頁面應(yīng)用而言,上報步驟是將頁面window對象上的__coverage__對象上報到Canyon服務(wù)端,對于單頁面應(yīng)用來說,相對來說比較簡單,在所有測試內(nèi)容都在單頁面應(yīng)用內(nèi),覆蓋率數(shù)據(jù)會常駐在window對象中,對于多頁面應(yīng)用而言,路由的跳轉(zhuǎn)會導(dǎo)致window對象的重制,丟失coverage對象。所以這個時機(jī)是至關(guān)重要的,經(jīng)過大量實踐驗證,我們找到了瀏覽器的onvisiblechange方法。
- visibilitychange
在瀏覽器可見性改變的時候上報覆蓋率數(shù)據(jù),值得一提的是,對于visibilitychange這種可能會導(dǎo)致重復(fù)數(shù)據(jù)上報,但是對于覆蓋率統(tǒng)計來說,未執(zhí)行到的代碼多次合并來說不會影響覆蓋率的具體指標(biāo)數(shù)據(jù)統(tǒng)計。
- fetchLater
Chrome 瀏覽器正在積極引入一個革命性的 JavaScript API——fetchLater()。這個全新的 API 旨在徹底簡化關(guān)閉頁面時的數(shù)據(jù)發(fā)送過程,確保即使在頁面關(guān)閉后或用戶離開的情況下,請求也能在未來某個時刻被安全、可靠地發(fā)出。
這個API的推出時令人振奮的,可以很好的解決多頁面(MPA)收集難的問題,只需要在瀏覽器關(guān)閉時收集。
注:fetchLater() 已在 Chrome 中提供,用于在版本 121(2024 年 1 月發(fā)布)開始的原始試驗中供真實用戶測試,該試驗將持續(xù)到 Chrome 126(2024 年 7 月)。
六、聚合
覆蓋率數(shù)據(jù)的來源是同一版本的代碼,覆蓋率數(shù)據(jù)是可以聚合的,Canyon內(nèi)部使用reportID來關(guān)聯(lián)測試用例和細(xì)分聚合維度。這樣做可以讓海量的覆蓋率數(shù)據(jù)聚合成有限個,即Case的數(shù)量。
/**
* 合并兩個相同文件的文件覆蓋對象實例,確保執(zhí)行計數(shù)正確。
*
* @method mergeFileCoverage
* @static
* @param {Object} first 給定文件的第一個文件覆蓋對象
* @param {Object} second 相同文件的第二個文件覆蓋對象
* @return {Object} 合并后的結(jié)果對象。請注意,輸入對象不會被修改。
*/
function mergeFileCoverage(first, second) {
const ret = JSON.parse(JSON.stringify(first));
delete ret.l; // 移除派生信息
Object.keys(second.s).forEach(function (k) {
ret.s[k] += second.s[k];
});
Object.keys(second.f).forEach(function (k) {
ret.f[k] += second.f[k];
});
Object.keys(second.b).forEach(function (k) {
const retArray = ret.b[k];
const secondArray = second.b[k];
for (let i = 0; i < retArray.length; i += 1) {
retArray[i] += secondArray[i];
}
});
return ret;
}
端到端測試的覆蓋率數(shù)據(jù)特點之一是單體數(shù)據(jù)體積大,在項目整體插樁的情況下相當(dāng)于整體源代碼體積的30%。攜程Trip.com flight站點的預(yù)定頁UI自動化case上報次數(shù)每次可達(dá)2000次,每次10M數(shù)據(jù),這樣的數(shù)據(jù)量對于Canyon服務(wù)端來說是一個巨大的挑戰(zhàn)。
對于單條數(shù)據(jù)大且高頻次的數(shù)據(jù)上報場景,很難做到實時數(shù)據(jù)聚合計算。Canyon采用消息隊列的形式來消費數(shù)據(jù),并且設(shè)計成無狀態(tài)服務(wù),適用于云原生時代的容器化部署,可通過HPA彈性伸縮容來應(yīng)用不同場景下的測試覆蓋率上報。
七、報告
對于覆蓋率報告展示,我們沿用了istanbul-report的界面風(fēng)格,但是由于istanbul-report只提供了靜態(tài)html文件的生成,不適合現(xiàn)代化前端水合數(shù)據(jù)生成html的模式,為此我們參考了它的源碼,使用了monaco-editor標(biāo)記源代碼覆蓋率。
const decorations = useMemo(() => {
if (data) {
const annotateFunctionsList = annotateFunctions(data.coverage, data.sourcecode);
const annotateStatementsList = annotateStatements(data.coverage);
return [...annotateStatementsList, ...annotateFunctionsList].map((i) => {
return {
inlineClassName: 'content-class-found',
startLine: i.startLine,
startCol: i.startCol,
endLine: i.endLine,
endCol: i.endCol,
};
});
} else {
return [];
}
}, [data]);
經(jīng)過著色后的效果:
八、變更代碼覆蓋率
對于變更代碼覆蓋率,我們統(tǒng)計的公式是覆蓋到的新增代碼行/所有新增代碼行。
通過配置compareTarget來指定對比目標(biāo),再聯(lián)合gitlab的git diff接口獲取變更代碼行結(jié)合覆蓋率數(shù)據(jù)計算。
/**
* returns computed line coverage from statement coverage.
* This is a map of hits keyed by line number in the source.
*/
function getLineCoverage(statementMap:{ [key: string]: Range },s:{ [key: string]: number }) {
const statements = s;
const lineMap = Object.create(null);
Object.entries(statements).forEach(([st, count]) => {
if (!statementMap[st]) {
return;
}
const { line } = statementMap[st].start;
const prevVal = lineMap[line];
if (prevVal === undefined || prevVal < count) {
lineMap[line] = count;
}
});
return lineMap;
}
九、react native 覆蓋率收集方案
攜程的移動端技術(shù)棧主要是react native,好消息是對于我們的插樁方案一樣適用,因為都是基于babel編譯。并且得力于得力于公司內(nèi)部的react native項目結(jié)構(gòu)統(tǒng)一,我們將編譯時插樁做到了流水線中,在流水線中分別打包“正常包”和”插樁包“,這樣搭配UI自動化可以形成一套完整的錄制回放覆蓋率指標(biāo)收集的測試體系。
利用websocket暴露模擬器內(nèi)覆蓋率數(shù)據(jù):
// 創(chuàng)建WebSocket連接
const socket = new WebSocket('ws://localhost:8080');
// 當(dāng)WebSocket連接打開時觸發(fā)
socket.onopen = () => {
console.log('Connected to coverage WebSocket server');
};
// 當(dāng)收到WebSocket消息時觸發(fā)
socket.onmessage = event => {
try {
if (JSON.parse(event.data).type === 'getcoverage') {
// 發(fā)送覆蓋率數(shù)據(jù)
socket.send(JSON.stringify(payload));
}
} catch (e) {
console.log(e);
}
};
// 當(dāng)WebSocket連接關(guān)閉時觸發(fā)
socket.onclose = () => {
console.log('Disconnected from coverage WebSocket server');
};
目前攜程機(jī)票部門的APP模塊均已接入Canyon,經(jīng)過實踐istanbuljs可以很好的對其進(jìn)行插樁及覆蓋率數(shù)據(jù)收集,測試團(tuán)隊在每次生產(chǎn)發(fā)布前會以Canyon的覆蓋率數(shù)據(jù)指標(biāo)來衡量此次發(fā)布的質(zhì)量情況。
十、覆蓋率提升優(yōu)先級列表
在用戶最初接入Canyon系統(tǒng)時,會面臨一個挑戰(zhàn):如果沒有大量的UI自動化測試用例,大型應(yīng)用的代碼覆蓋率會顯得尤為低下。一開始,僅僅提供一個Istanbul代碼覆蓋率報告,并不能有效指導(dǎo)團(tuán)隊如何提高覆蓋率,這讓大家感到困惑和無所適從。
為了解決這個問題,我們進(jìn)行了深入的調(diào)研,并發(fā)現(xiàn)公司已經(jīng)有了一個成熟的生產(chǎn)環(huán)境代碼覆蓋率收集系統(tǒng)。基于這一發(fā)現(xiàn),我們決定將這個系統(tǒng)的數(shù)據(jù)與我們自己的覆蓋率數(shù)據(jù)相結(jié)合,創(chuàng)建了一個“覆蓋率提升優(yōu)先級列表”。這個列表的目的是為開發(fā)團(tuán)隊提供明確的指引,幫助他們了解在哪些方面可以優(yōu)先提升代碼覆蓋率。
為了使這個指引更加科學(xué)和實用,我們制定了一個覆蓋率權(quán)重公式:
生產(chǎn)環(huán)境覆蓋率×100×0.3 + (1 - 測試覆蓋率)×100×0.3 + 函數(shù)數(shù)量×0.2
通過這個公式,我們能夠優(yōu)先識別出那些生產(chǎn)環(huán)境使用率高、行數(shù)多,測試覆蓋率低的代碼文件,從而為開發(fā)團(tuán)隊提供針對性的提升建議。這樣的方法不僅提高了代碼質(zhì)量,也增強(qiáng)了我們對整體覆蓋率的掌控。
十一、社區(qū)推廣
從這篇文章發(fā)表時起,我們將正式開源Canyon。JavaScript是時下最流行的編程語言,但是端到端測試覆蓋率收集領(lǐng)域一直空白,我們的代碼開發(fā)基于了istanbuljs,monaco editor等優(yōu)秀開源項目,我們有信心推出Canyon開源可以贏得社區(qū)的反響,并且可以有大量JavaScript開發(fā)者參與進(jìn)來。
Canyon在未來還有很大發(fā)展空間,例如生產(chǎn)環(huán)境插樁收集還未有待驗證嘗試,與playwright、puppeteer、cypress等自動化測試的工具還沒有深度鏈接,這些都已經(jīng)規(guī)劃到了未來的開發(fā)計劃中。希望在未來Canyon可以在攜程及社區(qū)里有更多人參與建設(shè)。