weixin_39816260
weixin_39816260
2020-12-28 07:05

update expected docx when env variable UPDATE_SNAPSHOT is defined

When making changes to a docx generation test, it is necessary to update the expected output. This change makes it easy to do so without requiring any additional code by simply defining the UPDATE_SNAPSHOT when executing tests.

For example:


UPDATE_SNAPSHOT=1 bundle exec rake TEST=test/executable_test.rb

Inspired by Jest's --updateSnapshot command and snapshot testing model:

  • https://jestjs.io/docs/en/snapshot-testing

NB: assert_docx_equal will always pass when UPDATE_SNAPSHOT is set.

该提问来源于开源项目:senny/sablon

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

8条回答

  • weixin_39623244 weixin_39623244 4月前

    I'm not sold on this. While I do think it's a pain that even touching an MS Word doc will cause differences even if nothing is actually changed allowing something like this would make it easy for someone to commit differences that shouldn't be by accident.

    When I need to make bulk changes that I've validated I tend to run something like rake |& grep 'cp /' and then just copy and paste the output. In principle using something like xargs could automate the process (maybe even piping straight into bash would work). This also avoids adding any extra complexity to the code.

    Does that sound like a suitable solution?

    点赞 评论 复制链接分享
  • weixin_39816260 weixin_39816260 4月前

    I'm not sold on this. While I do think it's a pain that even touching an MS Word doc will cause differences even if nothing is actually changed allowing something like this would make it easy for someone to commit differences that shouldn't be by accident.

    I do agree that the user should always be reviewing changes and be aware of what they are accepting. In an ideal world, there might be an interactive version of rake like jest that shows the diff and prompts whether to update the snapshot:

    https://jestjs.io/docs/en/snapshot-testing#interactive-snapshot-mode

    But Jest also offers the command line option as well, similar to this. It still requires explicitly adding the env variable to change behavior, so I think it's not that likely to happen on accident. Perhaps if you re-ran a command, but that could also happen if you were using a xargs pipeline or something else like you propose.

    Using xargs could accomplish the same thing, but requires the user know an additional language (not everyone is familiar with shell scripting, or even uses a platform with a unix shell) and figure out/remember some undocumented commands that might break if the test output format changes. Using the pipe also obscures other results of the tests themselves.

    This adds very little new to code to the project and makes it very easy to use without needing to know any shell language.

    We've been using this in our own project that uses sablon for 6 months now and have been very happy with it; we've not accidentally committed any wanted changes so far.

    点赞 评论 复制链接分享
  • weixin_39833454 weixin_39833454 4月前

    I'm in agreement with . From a user perspective, I would not expect an assertion to have any kind of side effects. Sample template management is up to the individual project and I don't think sablon needs to offer something out of the box. In the end, it's just copying a file.

    If that workflow works well for your project that's great but I don't think this needs to be handled specifically by the gem.

    点赞 评论 复制链接分享
  • weixin_39816260 weixin_39816260 4月前

    Unfortunately, n my project, the copy doesn't work because the test output is being written to a temporary directory:

    
           If the generated document is correct, the sample needs to be updated:
             cp /var/folders/jq/lwhvx_mn1kn8_56t2vg01tgr6ygk3g/T/one-year-referral.actual.docx20191230-74354-1k7urul /Users/pimlottc-gov/projects/docgen/spec/requests/proposal-letter.expected.docx
    
    [...]
    
    $ cp /var/folders/jq/lwhvx_mn1kn8_56t2vg01tgr6ygk3g/T/one-year-referral.actual.docx20191230-74354-1k7urul /Users/pimlottc-gov/projects/docgen/spec/requests/proposal-letter.expected.docx
    cp: /var/folders/jq/lwhvx_mn1kn8_56t2vg01tgr6ygk3g/T/one-year-referral.actual.docx20191230-74354-1k7urul: No such file or directory
    
    点赞 评论 复制链接分享
  • weixin_39833454 weixin_39833454 4月前

    Well, each project will be different. I usually place a tmp/ folder in my project that is not under source control. You might have different constraints and pursue a different approach. That's why I prefer that sample template management is outside the scope of this gem. A team will make better choices given their environment and constraints.

    点赞 评论 复制链接分享
  • weixin_39816260 weixin_39816260 4月前

    I hear you, and I understand why this probably won't be merged. I just wanted to try to make a clear, simple method to easily update expected docs, so that users won't end up making hacks like temporarily changing their test code to update them and then accidentally committing them.

    I've been guilty of this before:

    
          actual_file = Tempfile.new("proposal.actual.docx")
          # uncomment to update expected file
          # actual_file = "{Rails.root}/spec/requests/proposal.expected.docx""
          assert_docx_equal "#{Rails.root}/spec/requests/proposal.expected.docx", actual_file.path
    

    Updating expected text outcome is often a pain that gets worse the more complicated the file format is, unfortunately.

    点赞 评论 复制链接分享
  • weixin_39623244 weixin_39623244 4月前

    Thank you for sharing your work and the idea! I like it in a general sense but it's just not a good fit here because of the complex file format being dealt with. While it's not being merged users looking for a similar option may stumble across this PR and can use it as a starting place in their own helper code.

    点赞 评论 复制链接分享
  • weixin_39816260 weixin_39816260 4月前

    Following up on 6e250b3, this makes assert_docx_equal more useful by making it easier to update the expected docx outputs.

    点赞 评论 复制链接分享

相关推荐