Needle 项目技术文档

1. 安装指南

1.1 安装依赖

在安装 Needle 之前，请确保已安装以下依赖项：

• Python（建议使用 Python 3.x）
• pip（Python 包管理工具）
• Selenium（用于浏览器自动化）
• nose（用于测试框架）

1.2 安装 Needle

可以通过 pip 安装 Needle：

pip install needle

1.3 安装 Sphinx（可选）

如果需要自行构建文档，请安装 Sphinx：

pip install sphinx

2. 项目的使用说明

2.1 创建测试用例

Needle 主要用于测试网页的视觉效果，特别是 CSS、字体、图片等渲染是否正确。以下是一个简单的测试用例示例：

from needle.cases import NeedleTestCase

class BBCNewsTest(NeedleTestCase):
    def test_masthead(self):
        self.driver.get('http://www.bbc.co.uk/news/')
        self.assertScreenshot('#blq-mast', 'bbc-masthead')

在这个示例中，测试用例会打开 BBC 新闻页面，并检查页面顶部栏的视觉效果是否与预期一致。

2.2 运行测试

可以使用 nose 运行测试用例：

nosetests test_bbc.py

2.3 保存基准截图

在首次运行测试时，需要保存基准截图。可以使用 --with-save-baseline 选项：

nosetests test_bbc.py --with-save-baseline

这将生成基准截图，并保存在 screenshots/baseline/ 目录下。

3. 项目API使用文档

3.1 NeedleTestCase

NeedleTestCase 是 Needle 的核心测试类，继承自 unittest.TestCase。它提供了以下主要方法：

• assertScreenshot(selector, filename): 用于截取指定元素的截图，并与基准截图进行比较。
• driver.get(url): 打开指定的 URL。

3.2 自定义 WebDriver

可以通过重写 get_web_driver() 方法来指定使用的浏览器：

from needle.cases import NeedleTestCase
from needle.driver import NeedlePhantomJS

class MyTests(NeedleTestCase):
    @classmethod
    def get_web_driver(cls):
        return NeedlePhantomJS()

3.3 设置视口大小

可以通过 set_viewport_size() 方法设置浏览器视口的大小：

from needle.cases import NeedleTestCase

class MyTests(NeedleTestCase):
    def test_something(self):
        self.set_viewport_size(width=1024, height=768)

4. 项目安装方式

4.1 通过 pip 安装

最简单的安装方式是通过 pip：

pip install needle

4.2 从源码安装

如果需要从源码安装，可以按照以下步骤操作：

1. 下载源码包。
2. 解压源码包。
3. 进入解压后的目录。
4. 运行安装命令：

python setup.py install

4.3 运行测试套件

安装 tox 后，可以通过以下命令运行 Needle 的测试套件：

tox

5. 总结

Needle 是一个强大的工具，用于自动化测试网页的视觉效果。通过本文档，您可以了解如何安装、使用 Needle，并掌握其 API 的使用方法。希望本文档能帮助您更好地理解和使用 Needle 项目。