‏n8n-check: تست رگرسیون برای ورک‌فلوهای n8n

n8n-check یه ابزار متن‌باز با لایسنس MIT هست که برای ورک‌فلوهای n8n (یه ابزار اتوماسیون که کارها رو با وصل کردن نودها به هم می‌سازه) تست رگرسیون می‌نویسه. بهش export ورک‌فلو، دادهٔ ورودی ساختگی و پاسخ‌های ساختگی HTTP رو می‌دی. خودش موتور واقعی n8n رو اجرا می‌کنه، درخواست‌ها و آیتم‌های خروجی رو چک می‌کنه و گزارش JSON و JUnit می‌نویسه.

مشکلی که حل می‌کنه اینه که یه ورک‌فلو می‌تونه بدون هیچ خطایی تموم بشه ولی دادهٔ مهم رو گم کنه. مثال خود پروژه یه فیلتر قدیمیه که از نُه ردیف ورودی، هر هشت ردیف مفید رو حذف می‌کنه و اجرا هنوز «موفق» حساب می‌شه. n8n-check با چک کردن دقیق آیتم‌های میانی و خروجی نهایی این رو می‌گیره. یه مثال دیگه هم retry هست: وقتی یه درخواست 503 گرفت، n8n نسخهٔ 2.41.7 هر دو آیتم ورودی رو دوباره می‌فرسته و جمعاً چهار درخواست ثبت می‌شه. یعنی آیتمی که موفق بوده هم دوباره ارسال می‌شه و سمت سرور باید idempotent باشه، یعنی تکرار یه درخواست نتیجه رو دوبار ثبت نکنه.

تست‌ها توی یه case file تعریف می‌شن. input.node نقطهٔ شروع رو با یه نود Code عوض می‌کنه که دادهٔ ساختگی برمی‌گردونه. هر نود HTTP Request باید یه mock داشته باشه که URLش به یه سرور محلی هدایت می‌شه و احراز هویتش برداشته می‌شه. expect.count تعداد دقیق درخواست‌ها رو چک می‌کنه و assertions آیتم‌های خروجی یه نود رو. از نسخهٔ 0.1.6 هم count و pluck اضافه شدن تا مثلاً فقط json.id مقایسه بشه و timestampهای متغیر مشکل‌ساز نشن. فیلد اختیاری stopAfter هم اجرا رو بعد از یه نود قطع می‌کنه تا مثلاً قبل از ارسال به Slack فقط تبدیل داده تست بشه.

یه نمونهٔ واقعی تو README باگی هست که یه آبجکت داخل یه رشتهٔ JSON گذاشته شده و به [object Object] تبدیل می‌شه. اصلاحش فقط عوض کردن یه expression توی jsonBody هست تا خود آبجکت برگرده:

- ={ "shortId": {{ $json.shortId }}, "renderOptions": {{ $json.styling }} }
+ ={{ { shortId: $json.shortId, renderOptions: $json.styling } }}

برای استفاده سه راه هست: یه GitHub Action با یه فایل ورک‌فلو، اجرای محلی با Docker، یا نصب CLI از npm با نام @blucca/n8n-check که Node.js 24 به بالا لازم داره. Action به‌طور پیش‌فرض n8n 2.41.7 رو با شبکهٔ فقط loopback اجرا می‌کنه و با n8n-version می‌شه نسخهٔ دیگه‌ای انتخاب کرد تا قبل از آپگرید، رفتار دو نسخه مقایسه بشه. کد خروج 1 یعنی رگرسیون و 2 یعنی خطای تنظیمات. یه case builder تحت وب هم هست که فایل‌ها رو فقط توی مرورگر خودت نگه می‌داره.

نویسنده تأکید می‌کنه که فقط exportهای قابل‌اعتماد رو اجرا کنی، چون نودهای Code با دسترسی همون runner اجرا می‌شن. هر اجرا یه دیتابیس SQLite، پوشهٔ home و کلید رمزنگاری تازه می‌گیره. دادهٔ باینری، credentialها و تریگرهای webhook هنوز تو نسخهٔ 0.1 پشتیبانی نمی‌شن.

نکات کلیدی:

• ورک‌فلو با موتور واقعی n8n اجرا می‌شه، فقط درخواست‌های HTTP به mock محلی می‌رن
• نسخهٔ پیش‌فرض runtime، n8n 2.41.7 هست و نسخه با n8n-version قابل تغییره
• کد خروج 0 یعنی موفق، 1 یعنی رگرسیون، 2 یعنی خطای تنظیمات
• assertionهای count و pluck از v0.1.6 اضافه شدن
• نصب CLI از npm به Node.js 24+ نیاز داره، Action روی ubuntu-latest با Node.js 20+ کار می‌کنه
• دادهٔ باینری، credential و تریگر webhook تو v0.1 پشتیبانی نمی‌شن